Merge pull request #66 from RtlZeroMemory/create-textstyle-completeness

TextStyle completeness: add strikethrough/overline/blink with merge+encoding hardening

Author: RtlZeroMemory

docs/guide/styling.md

@@ -6,6 +6,27 @@ Rezi styling is designed to be:
 - **deterministic**: the same inputs produce the same frames
 - **composable**: styles inherit through containers
 
+## Text attributes
+
+`TextStyle` supports these boolean text attributes:
+
+- `bold`
+- `dim`
+- `italic`
+- `underline`
+- `inverse`
+- `strikethrough`
+- `overline`
+- `blink`
+
+New attribute SGR target mappings:
+
+- `strikethrough` -> SGR `9`
+- `overline` -> SGR `53`
+- `blink` -> SGR `5`
+
+These codes are the terminal mapping used by the backend emitter. Drawlist encoding carries all three attrs, and backend emission now supports `strikethrough`, `overline`, and `blink` end-to-end (terminal rendering still depends on terminal support).
+
 ## Inline styles
 
 Most visual widgets accept a `style` prop:
@@ -57,6 +78,7 @@ Style is merged from parent → child:
 
 - containers pass their resolved style to children
 - leaf widgets merge their own `style` on top
+- boolean attrs use tri-state semantics: `undefined` inherits, `false` disables, `true` enables
 
 Example:
 
@@ -87,5 +109,6 @@ ui.text(state.connected ? "Online" : "Offline", {
 - [Theme](../styling/theme.md) - Theme structure and built-ins
 - [Icons](../styling/icons.md) - Icon registry and fallback rules
 - [Focus styles](../styling/focus-styles.md) - Focus and disabled visuals
+- [Text style internals](text-style-internals.md) - Drawlist bit layout and merge/cache internals
 
 Next: [Performance](performance.md).

docs/guide/text-style-internals.md

@@ -0,0 +1,95 @@
+# Text Style Internals
+
+This page documents renderer-side text style behavior that is stable and test-covered.
+
+## Merge Semantics (Tri-State)
+
+Each boolean text attribute is merged independently with tri-state semantics:
+
+- `undefined`: inherit from base style
+- `false`: explicitly off
+- `true`: explicitly on
+
+This applies to all 8 boolean attrs:
+
+- `bold`, `dim`, `italic`, `underline`, `inverse`, `strikethrough`, `overline`, `blink`
+
+## Drawlist Attr Encoding (8-bit Layout)
+
+Drawlist style encoding packs boolean attrs into the low 8 bits of `style.attrs` (`u32`):
+
+- bit `0`: `bold`
+- bit `1`: `italic`
+- bit `2`: `underline`
+- bit `3`: `inverse`
+- bit `4`: `dim`
+- bit `5`: `strikethrough`
+- bit `6`: `overline`
+- bit `7`: `blink`
+
+Equivalent mask expression:
+
+```text
+attrs =
+  (bold ? 1<<0 : 0) |
+  (italic ? 1<<1 : 0) |
+  (underline ? 1<<2 : 0) |
+  (inverse ? 1<<3 : 0) |
+  (dim ? 1<<4 : 0) |
+  (strikethrough ? 1<<5 : 0) |
+  (overline ? 1<<6 : 0) |
+  (blink ? 1<<7 : 0)
+```
+
+The mapping is identical for `drawText(...)` and `drawTextRun(...)` segment styles.
+
+## Terminal SGR Mapping
+
+Terminal target SGR codes for the new attrs are:
+
+- `strikethrough` -> `9`
+- `overline` -> `53`
+- `blink` -> `5`
+
+Drawlist encoding carries these bits in `style.attrs`, and backend emission supports all three attrs (`strikethrough`, `overline`, `blink`) end-to-end. Terminal-visible behavior still depends on terminal support.
+
+## Renderer Merge Cache (Fast Path)
+
+`mergeTextStyle(base, override)` has a fast path when:
+
+- `base === DEFAULT_BASE_STYLE`
+- `override.fg` and `override.bg` are both `undefined`
+
+In that case, the renderer computes a compact key from per-attr tri-state values and uses direct array indexing into `BASE_BOOL_STYLE_CACHE`.
+
+Tri-state encoding per attr:
+
+- `0` = `undefined` (inherit)
+- `1` = `false`
+- `2` = `true`
+
+Key layout (2 bits per attr, 8 attrs total):
+
+```text
+key =
+  b
+  | (d  << 2)
+  | (i  << 4)
+  | (u  << 6)
+  | (inv<< 8)
+  | (s  << 10)
+  | (o  << 12)
+  | (bl << 14)
+```
+
+Cache sizing rationale:
+
+- 8 attrs * 2 bits = 16-bit key space
+- cache length is `65536` (`2^16`), so every possible key index is valid
+- tri-state value set uses only `0..2` per 2-bit slot, so current reachable combinations are a subset (`3^8 = 6561`), with room for full direct addressing
+
+Why this is used:
+
+- avoids per-merge object churn for common default-base boolean-only style merges
+- avoids hash-map overhead by using a fixed-size array lookup
+- keeps object identity stable for repeated equivalent style inputs on the hot path

packages/core/src/app/__tests__/partialDrawlistEmission.test.ts

@@ -141,6 +141,9 @@ function styleKey(style: TextStyle | undefined): string {
     style.italic ? "i1" : "i0",
     style.underline ? "u1" : "u0",
     style.inverse ? "v1" : "v0",
+    style.strikethrough ? "s1" : "s0",
+    style.overline ? "o1" : "o0",
+    style.blink ? "k1" : "k0",
     `fg:${colorKey(style.fg)}`,
     `bg:${colorKey(style.bg)}`,
   ].join("|");
@@ -623,6 +626,228 @@ describe("WidgetRenderer incremental drawlist emission", () => {
     );
   });
 
+  test("strikethrough-only style change in commit path matches full render", () => {
+    const viewport: Viewport = { cols: 32, rows: 6 };
+    const backend = createNoopBackend();
+
+    const viewFn = (s: Readonly<{ strike: boolean }>) =>
+      ui.column({}, [
+        ui.text("Header"),
+        ui.text("strike-target", { style: { strikethrough: s.strike } }),
+        ui.text("Footer"),
+      ]);
+
+    const partialBuilder = new RecordingBuilder();
+    const partialRenderer = new WidgetRenderer<{ strike: boolean }>({
+      backend,
+      builder: partialBuilder,
+      requestRender: () => {},
+    });
+
+    const fullBuilder = new RecordingBuilder();
+    const fullRenderer = new WidgetRenderer<{ strike: boolean }>({
+      backend,
+      builder: fullBuilder,
+      requestRender: () => {},
+    });
+
+    const planBootstrap = { commit: true, layout: true, checkLayoutStability: true } as const;
+    const planUpdate = { commit: true, layout: false, checkLayoutStability: false } as const;
+
+    const opsA = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { strike: false },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferA = applyOps(createFramebuffer(viewport), opsA);
+
+    const opsExpected = submitOps(
+      fullRenderer,
+      fullBuilder,
+      viewFn,
+      { strike: true },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferExpected = applyOps(createFramebuffer(viewport), opsExpected);
+
+    const opsPartial = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { strike: true },
+      viewport,
+      planUpdate,
+    );
+    const framebufferPartial = applyOps(framebufferA, opsPartial);
+
+    assertFramebuffersEqual(framebufferPartial, framebufferExpected);
+    assert.equal(
+      opsPartial.some((op) => op.kind === "clearTo"),
+      false,
+    );
+    assert.equal(
+      opsPartial.some(
+        (op) =>
+          op.kind === "drawText" &&
+          op.text === "strike-target" &&
+          (op.style?.strikethrough ?? false) === true,
+      ),
+      true,
+    );
+  });
+
+  test("overline-only style change in commit path matches full render", () => {
+    const viewport: Viewport = { cols: 32, rows: 6 };
+    const backend = createNoopBackend();
+
+    const viewFn = (s: Readonly<{ overline: boolean }>) =>
+      ui.column({}, [
+        ui.text("Header"),
+        ui.text("overline-target", { style: { overline: s.overline } }),
+        ui.text("Footer"),
+      ]);
+
+    const partialBuilder = new RecordingBuilder();
+    const partialRenderer = new WidgetRenderer<{ overline: boolean }>({
+      backend,
+      builder: partialBuilder,
+      requestRender: () => {},
+    });
+
+    const fullBuilder = new RecordingBuilder();
+    const fullRenderer = new WidgetRenderer<{ overline: boolean }>({
+      backend,
+      builder: fullBuilder,
+      requestRender: () => {},
+    });
+
+    const planBootstrap = { commit: true, layout: true, checkLayoutStability: true } as const;
+    const planUpdate = { commit: true, layout: false, checkLayoutStability: false } as const;
+
+    const opsA = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { overline: false },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferA = applyOps(createFramebuffer(viewport), opsA);
+
+    const opsExpected = submitOps(
+      fullRenderer,
+      fullBuilder,
+      viewFn,
+      { overline: true },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferExpected = applyOps(createFramebuffer(viewport), opsExpected);
+
+    const opsPartial = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { overline: true },
+      viewport,
+      planUpdate,
+    );
+    const framebufferPartial = applyOps(framebufferA, opsPartial);
+
+    assertFramebuffersEqual(framebufferPartial, framebufferExpected);
+    assert.equal(
+      opsPartial.some((op) => op.kind === "clearTo"),
+      false,
+    );
+    assert.equal(
+      opsPartial.some(
+        (op) =>
+          op.kind === "drawText" &&
+          op.text === "overline-target" &&
+          (op.style?.overline ?? false) === true,
+      ),
+      true,
+    );
+  });
+
+  test("blink-only style change in commit path matches full render", () => {
+    const viewport: Viewport = { cols: 32, rows: 6 };
+    const backend = createNoopBackend();
+
+    const viewFn = (s: Readonly<{ blink: boolean }>) =>
+      ui.column({}, [
+        ui.text("Header"),
+        ui.text("blink-target", { style: { blink: s.blink } }),
+        ui.text("Footer"),
+      ]);
+
+    const partialBuilder = new RecordingBuilder();
+    const partialRenderer = new WidgetRenderer<{ blink: boolean }>({
+      backend,
+      builder: partialBuilder,
+      requestRender: () => {},
+    });
+
+    const fullBuilder = new RecordingBuilder();
+    const fullRenderer = new WidgetRenderer<{ blink: boolean }>({
+      backend,
+      builder: fullBuilder,
+      requestRender: () => {},
+    });
+
+    const planBootstrap = { commit: true, layout: true, checkLayoutStability: true } as const;
+    const planUpdate = { commit: true, layout: false, checkLayoutStability: false } as const;
+
+    const opsA = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { blink: false },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferA = applyOps(createFramebuffer(viewport), opsA);
+
+    const opsExpected = submitOps(
+      fullRenderer,
+      fullBuilder,
+      viewFn,
+      { blink: true },
+      viewport,
+      planBootstrap,
+    );
+    const framebufferExpected = applyOps(createFramebuffer(viewport), opsExpected);
+
+    const opsPartial = submitOps(
+      partialRenderer,
+      partialBuilder,
+      viewFn,
+      { blink: true },
+      viewport,
+      planUpdate,
+    );
+    const framebufferPartial = applyOps(framebufferA, opsPartial);
+
+    assertFramebuffersEqual(framebufferPartial, framebufferExpected);
+    assert.equal(
+      opsPartial.some((op) => op.kind === "clearTo"),
+      false,
+    );
+    assert.equal(
+      opsPartial.some(
+        (op) =>
+          op.kind === "drawText" &&
+          op.text === "blink-target" &&
+          (op.style?.blink ?? false) === true,
+      ),
+      true,
+    );
+  });
+
   test("incremental v2 cursor is emitted even when focused input is outside damage rect", () => {
     const viewport: Viewport = { cols: 40, rows: 8 };
     const backend = createNoopBackend();

packages/core/src/drawlist/__tests__/builder.alignment.test.ts

@@ -72,7 +72,11 @@ function expectOk(result: DrawlistBuildResult): Uint8Array {
   return result.bytes;
 }
 
-function readStringSpan(dv: DataView, stringsSpanOffset: number, index: number): { off: number; len: number } {
+function readStringSpan(
+  dv: DataView,
+  stringsSpanOffset: number,
+  index: number,
+): { off: number; len: number } {
   const spanOff = stringsSpanOffset + index * SPAN_SIZE;
   return {
     off: dv.getUint32(spanOff, true),