ekp/postmortem/20260729-text-property-live-layout.md

Keep KP Decisions Semantic and Buffer Layout Presentational

Historical note: the text-property projection decision remains current. The partial-KP live state machine described below was replaced by the native progressive model in 20260729-native-progressive-live-editing.md.

Context

The original editor integration inserted a reversible rendered string into the real buffer. Its marker properties made the transform recoverable, and save/copy/search adapters hid much of the representation, but arbitrary Elisp character APIs still observed synthesized spaces, newlines, and discretionary hyphens.

The required outcome was stronger than reversible formatting: the buffer's character stream itself had to remain the logical document. The user also excluded overlays and required existing-character text properties, specifically absolute-pixel min-width, real-space space-width, and line-prefix.

This exposed a second mistake in the old live mode. A function that produces an optimal completed paragraph is not automatically an editing algorithm. Running it after an idle delay caused unfinished lines to snap, performed whole-paragraph work for local edits, and had no explicit overflow, pullback, composition, or convergence policy.

The first deletion implementation also recalculated its look-behind from each backspace. Once two visual lines merged, the next deletion began at a new line boundary and moved the anchor left again. The source round trip was correct, but the projection accumulated an extra break because the recomputation boundary crept into the formerly stable prefix.

Decision

Separate layout decisions from representation.

ekp-layout-plan owns boxes/source offsets, line ranges, exact glue targets, indentation, chosen breaks, and discretionary-hyphen decisions. The public string renderer retains its compatible lossless physical returned string. The buffer renderer consumes the same plan but has no right to insert a character.

The buffer projection is:

• source ASCII space: ((space-width FACTOR) (min-width ((TARGET-PIXELS))));
• zero-source CJK/mixed gap: min-width on the preceding complete grapheme, targeting natural advance plus glue;
• indentation: line-prefix;
• explicit break/hyphen: a replacing display string on an existing complete grapheme that reproduces the grapheme, appends the optional hyphen, then a visual newline.

Every public property value is mirrored by an EKP owner property. Cleanup removes the public value only while it is still identical to the owned value. Updates use with-silent-modifications; owned properties are nonsticky. No buffer path creates an overlay.

Live editing uses a separate bounded state machine:

1. keep one stable source-marker anchor for a continuous editing flow, then snapshot and clear only its affected projected suffix;
2. keep the point-containing unfinished line naturally spaced;
3. commit the longest fitting prefix on overflow;
4. pull following material back after deletion;
5. stop when source position and a position-independent line signature match the old plan;
6. defer composition and reject stale generation work;
7. allow a complete quality pass only after leaving the paragraph or an explicit refill command.

The active anchor is released when the flow ends: leaving the paragraph, explicit refill, a hard-boundary reflow, conflict abandonment, or mode teardown. A new deletion starts one line earlier only when it first begins exactly at a visual-line boundary; subsequent backspaces reuse the same anchor. This makes overflow followed by deletion projection-identical.

Automatic work has a hard single-paragraph limit. An oversized paragraph stays naturally editable and diagnostic rather than entering an unbounded DP during mode enable, paste, or typing. ekp-refill-paragraph is the explicit request to pay that cost.

Text properties are buffer-wide, so the narrowest live window supplies one authoritative width. Wider windows may show unused space. Simultaneous different-width KP plans are not claimed.

Alternatives Rejected

Keep physical buffer text and add more adapters

No finite adapter list can change what arbitrary buffer-string, char-after, syntax, or third-party Elisp reads. This compensates at the wrong layer.

Use overlays

The user explicitly excluded them. Keeping an overlay backend would also create two projection ownership models and make lifecycle behavior harder to reason about.

Use min-width alone

It can only add width. Existing ASCII spaces sometimes need shrinking; space-width supplies that shrink and min-width supplies the exact pixel floor after rounding.

Use space-width alone

The factor is rounded by redisplay and is not an exact absolute-pixel guarantee. It also has no effect on tabs.

Reuse completed-paragraph formatting after every edit

Changing its trigger from idle to synchronous would remove the delay but still perform the wrong unit of work and would justify an unfinished line. The editing path needs its own active-line and convergence semantics.

Promise independent widths in multiple windows

One set of buffer text properties cannot encode two different break plans. Pretending otherwise would publish an overflowing plan in at least one window.

Consequences

• Direct character APIs, search, syntax, save, point, and markers operate on source characters.
• APIs that preserve or inspect text properties can still observe EKP projection metadata; copy/kill removes that owned metadata.
• Foreign replacing display ownership makes only the affected hard paragraph natural and diagnostic.
• Tabs/non-ASCII whitespace remain natural if an exact plan would require shrinking them.
• Layout property changes do not create layout-only undo or modified-state changes.
• Ordinary edits perform bounded local flow with no delayed whole-paragraph snap.
• Very long single paragraphs trade automatic KP quality for bounded input latency until the user explicitly requests refill.

Verification

The architecture requires three evidence layers:

• ERT for core plan/string parity, source and lifecycle invariants, exact property forms, live overflow/pullback/convergence, composition, undo, ownership, resize, multiwindow policy, and overload behavior;
• clean GUI probes for exact pixel glue, break/hyphen/indent rendering, point, region, mouse, and source invariants;
• dynamic before/immediate/settled recording for overflow and pullback, including source/projection hashes, zero overlays, pixel-fit assertions, and temporal review.

Final evidence and counts are recorded in the phase change/task documents, not retroactively copied into this decision record.

Rollback

Revert the text-property buffer renderer and live state machine together. Do not retain a mixed physical/text-property backend. The semantic plan and compatible string renderer can remain independently because their boundary does not depend on buffer projection.