# Native Surface Coverage

Prevent and investigate backdrop leaks, seams, stale clipping and rounded-corner...

- Repository: https://github.com/nowledge-co/con-terminal (651 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nowledge-co/con-terminal --skill native-surface-coverage -g -a claude-code -y`
Codex: `npx skills add nowledge-co/con-terminal --skill native-surface-coverage -g -a codex -y`
Cursor: `npx skills add nowledge-co/con-terminal --skill native-surface-coverage -g -a cursor -y`
Gemini CLI: `npx skills add nowledge-co/con-terminal --skill native-surface-coverage -g -a gemini-cli -y`

## Description

Prevent and investigate backdrop leaks, seams, stale clipping and rounded-corner artifacts when changing con pane/sidebar geometry, animation, transparency or native terminal composition.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Native surface coverage

Preserve con's glass material while keeping each moving pixel covered by its
correct owner. A darker result, passing layout test or clean log is insufficient.

## Identify the failure before choosing a fix

Record direction and trigger, tab orientation, compact/pinned/hover state,
pane/surface layout, input-bar visibility, theme, terminal/UI opacity, blur,
macOS version, display scale and release versus preview binary.

| Observation | Investigate |
| --- | --- |
| Different backdrop colors visible through adjacent surfaces at rest | Intended transparency; compare the same position and backdrop |
| A stable hairline or jagged curve | Physical-pixel endpoints, shared corner coverage, overlapping alpha |
| A broad moving strip, especially one that also clips text | Native frame/mask/GPUI presentation timing; measure successive video frames |
| Correct model bounds but wrong native output after reuse | Attached masks, native backing-layer replacement and actual framebuffer dimensions |

Remote desktop or OS differences are verification limits, not presumed causes.
For a transient report, inspect a recording before treating a helper-level bug
as the root cause. A strip advancing with per-frame travel is evidence of a
presentation mismatch, not a reason to thicken its edge.

## Trace the real rendering path

Read the relevant sections, not every historical investigation:

- [Workspace composition](../../crates/con-app/src/workspace/render.rs) and
  [frame geometry](../../crates/con-app/src/workspace/frame.rs).
- [Pane ownership](../../crates/con-app/src/pane_tree.rs),
  [native host](../../crates/con-app/src/ghostty_view.rs) and
  [AppKit masks](../../crates/con-app/src/objc/ghostty_surface_trampoline.m).
- [Native presentation contract](../../docs/design/native-terminal-presentation.md).
- For cache/opacity changes, [GPUI cache guidance](../gpui-cache-aware/SKILL.md).

The rest: https://github.com/nowledge-co/con-terminal/blob/HEAD/skills/native-surface-coverage/SKILL.md