# Your typing, above your hands: building Typing on Top

*A development journal about a tiny macOS utility, a surprisingly useful notch, and all the details hiding inside “just mirror the text.”*

The idea started with a very physical problem. When you type into a field near the bottom of your screen, your fingers can block the words you are trying to follow. You look down, lean in, adjust your hands, and interrupt the thought you were writing.

Typing on Top gives those words another place to be seen: a black strip beside the MacBook notch. You continue typing in the original application. The strip mirrors your text and insertion point without taking keyboard focus. Your eyes can stay higher on the screen.

That description is simple. Making it feel simple took considerably more work.

## The notch you cannot see in a screenshot

Our first useful design references were edited screenshots. A normal screenshot does not show the physical notch as an obstruction, so the references marked it in red and the available mirror area in green.

Those annotations revealed two wasted opportunities. The original strip was capped at 420 logical points, leaving a large amount of usable space to its right. Its internal spacing also consumed too much of an already shallow band.

We expanded the right-side strip to reach the screen edge. Then we had to decide what “beside the notch” really meant. A small overlap behind the notch was not enough. The desired shape began at the **left edge of the notch**, covered the whole notch region in black, and continued to the right edge of the screen. Only the text needed to begin at the notch's **right edge**.

That distinction became a central design rule: background geometry and text geometry are separate controls.

## Points, pixels, and a clean black edge

AppKit works in logical points. Hardware screenshots and physical display pixels are a different coordinate system. A request to move something ten pixels might mean roughly five points on a Retina display, depending on scaling.

We used `NSScreen.safeAreaInsets` and the auxiliary top-left and top-right areas to locate the notch dynamically. Hard-coding a horizontal position from one 14-inch screenshot would have broken under another display scaling setting.

Height took a different path. We started with a taller minimum band, trimmed it, and eventually settled on a configurable **32-point default**. That is a product default, not a claim that every MacBook and every scaling mode has identical notch dimensions. The user can adjust the height from 24 to 96 points.

The surface uses device black. A transparent panel background allows the content surface to define the lower-left rounding without a rectangular window background showing through it. But rounding turned out to require restraint: a separate 9-point corner radius on the scrolling text surface clipped the first “O” at small font sizes. We removed that internal rounding for docked layouts.

The outside silhouette and the inside text clipping area have different jobs. Treating them as one shape caused an unnecessary visual defect.

## Making a very small interface extremely configurable

The settings grew from a couple of menu items into a dedicated window. That was the right place for the detail: a menu bar should provide quick access, not become a long checklist of every possible adjustment.

The settings now cover:

- Element height, horizontal start, right-edge inset, and vertical text offset.
- Font sizes from 5 to 36 points.
- Letter expansion and wrapped-line spacing.
- Current-line-only or wrapped-context display.
- White, red, yellow, or green text.
- Red, white, yellow, green, or hidden cursor.
- Activation threshold and an always-on option for focused text fields.
- Experimental placement modes, Accessibility access, and defaults reset.

The agreed visual defaults are 32-point height, 18-point type, white text, a green cursor, a text start two points beyond the notch, a four-point vertical offset, and no extra right-edge inset. Current-line-only is the default display mode. The default activation threshold is 85% from the top, with always-on disabled.

Existing saved choices persist. Changing the default does not silently overwrite every user's preferences; Reset to Defaults applies the new profile.

The older floating, left-of-notch, and full-width layouts remain accessible through an experimental toggle. The right-of-notch experience is the main focus.

## Preview should behave like a workbench

An eight-second sample was useful at first. It became frustrating once the settings were detailed enough to require careful comparison. A preview that disappears while someone adjusts a slider is not much of a preview.

Opening settings now starts a persistent preview. Editing a multiline sample updates the mirror immediately. Closing the window ends that preview session and returns control to normal activation.

The editable sample matters. Short placeholder text does not reveal what happens with long sentences, hard line breaks, or a cursor near the edge. People need to test the kind of text they actually write.

There is a privacy distinction here: real mirrored field content is not stored as history. The custom preview sample is saved locally with preferences, so it is available next time settings opens.

## Two half-lines are worse than one whole line

One screenshot showed the exact failure: the lower half of one line and the upper half of the next. Scrolling a multiline text view inside a narrow strip had made both lines unreadable.

The solution was to make the display policy explicit. **Current line only** extracts the logical line containing the caret and fits a window of that line into the available width. **Wrapped context** retains multiple lines and exposes line spacing for people who prefer that view.

Line spacing has no visible effect when only one line is rendered. We had to explain that distinction rather than imply that every slider changes every display mode.

Very large type can still exceed a very short band. Fine-grained controls give flexibility, but cannot make contradictory geometry disappear.

## The cursor that invented a space

Initially, we inserted a colored vertical glyph into the attributed string to represent the cursor. It looked plausible at the end of a sentence. In the middle of a word, it revealed the mistake: inserting the cursor glyph pushed the next character away and created an apparent space that did not exist in the source.

The cursor is now a visual overlay positioned from text layout. It does not occupy a character slot or alter the string. Selection highlighting also remains a visual treatment.

This is a small but important trust issue. A mirror must not invent whitespace while asking the user to rely on it for proofreading.

## Width, expansion, and the tiny-font regression

Letter width and the right-edge inset must share the same geometry. Our first capacity calculation used an estimated character width. When the inset and letter expansion changed together, the estimate could fit more text than the strip could actually display.

We changed the fitting code to wait for layout and measure attributed substrings with the configured font and expansion against the available viewport width. The fit reserves a little space for the cursor and uses a search to find a suitable text window around it.

There was also a regression along the way. A font-descriptor matrix intended to scale glyph width interfered with the configured point size, producing almost unreadably tiny text. We restored the normal monospaced font at the chosen size and returned width adjustment to attributed-text expansion.

The lesson was practical: measuring, rendering, and clipping must agree. A successful build does not prove that the letters still look right.

## Reading another app without taking it over

The mirror reads macOS Accessibility information. It asks which control is focused, whether it is editable or secure, what text it exposes, and where its selection lies. It refreshes periodically without moving the source cursor or taking keyboard focus.

Native fields and standard browser inputs give us the best baseline. Web and Electron editors can put focus on a containing web area rather than the editable child. The service therefore includes bounded discovery of editable descendants, plus information from actual clicks.

Password fields are excluded. Some custom controls simply do not expose enough information to mirror reliably. Accessibility permission is required; it is not optional setup decoration.

## Long documents are not just longer strings

Obsidian made this particularly clear. Its CodeMirror editor can virtualize a document, and the text exposed through one accessibility attribute may not line up with a document-wide selection from another snapshot.

Pairing a full `AXValue` with a selection from a different representation can put the cursor on the wrong row. Markdown and links are visible when the failure happens, but that does not establish Markdown syntax as the cause. The important issue is whether the text and offsets refer to the same representation at the same time.

We introduced bounded reads around the selection through `AXStringForRange`, using UTF-16 offsets because that is how the accessibility ranges are expressed. The text-window origin stays stable while there is enough room around the caret. Line-break normalization also maps caret and selection offsets instead of simply replacing characters and hoping the indices still fit.

For the experimental Obsidian path, reads now try smaller windows—512, 256, then 96 UTF-16 units—rather than falling back to the entire document. An established retained window may include an edge buffer. Repeated failures clear cached editor references and trigger discovery again. New clicks also allow immediate rediscovery.

During certain read failures the implementation can retain the last successful Obsidian mirror. That is a recovery measure, not proof that the retained text is current. We should continue to distinguish a successful read from a stale display when refining this behavior.

## A moving caret and an asynchronous source

Some web editors publish changed text before they publish the corresponding selection. We added a stabilizer that can infer a caret after an obvious local edit.

This heuristic also caused trouble. A trailing-caret assumption could keep the mirror at the end after a real edit in the middle. A regression test captured that conflict: the local edit inferred the right position, then the trailing fallback overwrote it. The fix lets the edit evidence clear that assumption.

There is a limit to inference. Recovering the insertion point after a text change does not prove that every arrow-only move is correctly exposed by every editor. Live testing remains necessary.

## The threshold was measuring the wrong thing

The product is supposed to help when typing moves into the lower part of the screen. Measuring the center of the whole field does not satisfy that requirement. A large textarea can stay in place while its caret moves down several rows.

Activation therefore began reading the accessibility bounds of the selection or caret. When those bounds cannot be used, it falls back to the field position. Always-on bypasses the positional threshold but still requires an eligible focused field and retains secure-field protection.

That change exposed coordinate problems. Screen geometry in AppKit and accessibility geometry need careful conversion. We added consistency checks against the focused field and candidate coordinate orientations. These are compatibility heuristics; passing the core geometry tests is not the same as verifying Terminal, a browser, and Obsidian in their real states.

## The Obsidian flash that finally explained itself

The most revealing report was this: click below the threshold, see the mirror briefly, then watch it disappear. Click into another app, and the mirror works again.

We had been investigating document size, timeout recovery, and virtualized text. But there was a simpler activation bug in the code: **the click point was used for one refresh, then discarded**. On the next refresh, activation could use stale caret bounds or the center of the entire document. The same editing session passed the threshold once and failed it a moment later.

The final change in this iteration retains a confirmed Obsidian click as the activation anchor for that editor session. A new click, app change, a different editor identity, or a changed editor frame invalidates the match. Obsidian discovery also no longer takes a recent-search shortcut that could temporarily produce no editor.

After that change, the user reported that Obsidian was working nicely.

There is a tradeoff: this Obsidian path uses a stable click anchor rather than continuously trusting every reported caret coordinate. That makes the observed session more reliable, but means the activation semantics differ from applications with dependable caret bounds.

## Placeholder text is another kind of content

The “Work with ChatGPT” placeholder kept appearing in the mirror. Our first filter looked for an explicit placeholder attribute. That was not sufficient for the observed app.

The later filter also considers reported character count and matching description, title, and help metadata. This is heuristic filtering, not a universally reliable way to distinguish user-authored text from presentation. Matching legitimate text and metadata is possible. We did not establish a final live confirmation for every placeholder case, so this remains a compatibility detail to test rather than a solved claim to put in marketing copy.

## Checkpoints and honest verification

Before the later compatibility experiments, we documented the product and pushed checkpoint `5895a0d` to GitHub. Subsequent changes were kept local while they were being tried. That preserved a recoverable baseline while allowing quick iterations.

The automated suite covers core text-window, normalization, caret-stabilization, and screen-threshold behavior. At the time of this work, the reported suite contained 15 passing tests. Those checks do not cover the complete live Accessibility behavior of third-party editors.

A release build proves that the code compiles. A preview proves that sample text can be rendered. Only testing the actual editor reveals click-to-focus races, stale selection data, moving windows, and disappearing overlays. The user's repeated tests were essential to this work.

## What the small strip became

The result is still a small app. That is deliberate. The important work lives in the relationship between a physical obstruction, a tiny display area, and the words someone is trying to write.

The notch geometry, the true-black surface, the absence of invented cursor spacing, the live preview, the configurable edges, and the recovery behavior all serve that same purpose: make it easier to see your typing without interrupting it.

The best version of this tool is one you stop noticing—until you turn it off and find yourself looking down again.
