tp/CHANGELOG.md

# Changelog

All notable changes to the tp library are documented here.

## Unreleased

### Added

- `tp-transaction-participate` lets a client promote rollback-capable opaque side state after all affected surfaces publish but before source values commit. Participant keys are unique per outer transaction, failure rolls participants back in reverse publication order, and observers still run only after the transaction exits.
- `tp-propertize`, `tp-apply`, and `tp-watch` now provide simple one-shot string, one-shot buffer-range, and reactive existing-text entry points over the same schema/cascade/projector and retained properties-surface core.
- TP 1.0 retained surfaces now provide defensive pure plans, prepare-scoped object identity, keyed/positional reconciliation, `content` and `properties` capabilities, marker-backed range anchors, same-surface overlapping property contributions, compare-before-write conflicts and explicit rebase, common-prefix/suffix text edits, property-run diffs, side indexes, opaque client state, generic reports, lifecycle cleanup, and atomic multi-buffer publication with exact rollback. Pure materialization uses the same plan semantics without leaving live handles or subscriptions.
- TP 1.0 signals and bindings now form an exact source→binding and binding→binding dependency graph with conditional rewiring, memoized equality cutoffs, transaction-local candidate signal values, deduplicated topological flushing, nested-write stabilization, rollback, cycle paths, owner disposal, buffer-scoped sources, variable adapters, and public scheduler counters. The legacy layer scanner remains isolated only until the retained-surface cutover.
- The first TP 1.0 runtime slice: `tp-style.el` provides atomic namespaced property schemas, structured subject selectors and combinators, deterministic origin/importance/layer/specificity/scope/source-order cascade, property-specific inheritance, tagged CSS-wide values, custom-property fallback/cycle handling, explicit `tp-computed` value sources, named declarations, provenance, and final Emacs-property projection. Ordinary function values remain literal.
- Internal Stage 2 canonical façade records and dataflow:
  `tp--native-range`, `tp--presence`, `tp--request`, `tp--match`,
  and `tp--result`. Public entry points and historical return shapes
  remain compatible.
- Stage 3 text-only native façade in `tp-query.el`:
  `tp-lookup-result`, `tp-lookup`, `tp-property-change`,
  `tp-property-any`, `tp-property-not-all`, and
  `tp-with-mutation-policy`.
- Stage 4 managed lifecycle APIs: `tp-attach-managed-layers`,
  `tp-detach-managed-layers`, `tp-managed-layer-diagnostics`,
  `tp-managed-buffer-diagnostics`, `tp-managed-diagnostics`, and
  `tp-layer-transaction`.
- Stage 5 overlay-aware lookup modes for `tp-lookup`: `:char` and
  `:char-source` report Emacs character-property values and the
  winning overlay identity when an overlay wins.
- `docs/API-SEMANTICS.md` centralizes the current object/coordinate,
  mutation, presence/nil, search-result, layer-ownership, `tp-text`,
  error, and hidden-stack conflict contracts.
- `tp-any-value`, a unique public sentinel for property-search wildcard
  matching when later positional arguments also need to be supplied.
- `tp-unresolved-layer` and `tp-layer-conflict` error types.
- `tp-reactive-observer-errors`, a newest-first structured record of
  isolated watcher callback failures.

### Fixed

- Initial `tp-text` rendering now preserves every embedded property
  interval for strings and buffers instead of spreading position-zero
  properties across the replacement.
- `tp-text` application preserves the caller's `tp-set`, `tp-reset`,
  or `tp-add` write semantics even when replacement text is unchanged.
- Explicit nil properties override embedded `tp-text` values.
- Non-parameterized layer redefinition refreshes managed regions with
  old/new ownership reconciliation: removed keys disappear, new keys
  replace them, and unrelated or externally changed values survive.
- Search APIs distinguish omitted VALUE (any directly present value)
  from explicit nil (a present nil value), with one presence-aware run
  scanner shared by strings and buffers.
- Removing the last nested sub-property removes the empty parent key
  consistently for strings and buffers.
- Stack NOERROR catches only unresolved layer specifications; errors
  from layer bodies and internal operations propagate.
- When hidden-layer full-stack storage detects an external direct
  property edit, stack decoding now signals `tp-layer-conflict` before
  any managed write instead of silently discarding the external value.
- Buffer transaction rollback tracks its live range with markers, so
  insertions and deletions inside the range are removed or restored
  together with the original text-property snapshot.

### Changed

- Transform and compute failures now propagate as business-output
  errors. A transform returning a non-string also signals. Watcher
  failures remain isolated observers, but are recorded structurally
  while the managed update continues.
- Managed layer entries now store `tp-meta` in authoritative
  `tp-layers` storage, including parameterized args and definition
  versions. Direct rendered properties and public stack queries strip
  `tp-meta`; historical returns remain unchanged.
- Parameterized mounted layer entries refresh from stored args after
  redefinition.
- Insert/copy/yank/stickiness/narrowing/indirect-buffer behavior is
  now documented as direct Emacs delegation with no tp wrapper.
- Overlay creation, movement, deletion, priority management, and
  lifecycle remain native Emacs responsibilities; tp only reports
  overlay-aware lookup results.
- `tp-with-mutation-policy` accepts only ordinary+respect,
  ordinary+inhibit, and silent+inhibit; silent+respect is rejected.
- Theme enable/disable events now increment theme generation and expose
  conservative refresh diagnostics. Reproducible benchmark evidence is
  recorded in `docs/BENCHMARKS.md`; timings are advisory baseline data,
  not release thresholds.

## 0.3.0 (2026-07-27)

### Added

Layer stack:

- **Layer visibility**: `tp-hide-layer` / `tp-show-layer` — a hidden
  layer stays in the stack (and keeps receiving reactive updates) but
  does not render; hiding the visible top reveals the next visible
  layer, and with every layer hidden the text renders bare.
  `tp-flatten-layers` merges only visible layers; `tp-merge-layers`
  excludes hidden matched layers' props.
- `tp-lower-layer` (mirror of `tp-raise-layer`) and a
  family-consistent `tp-rotate-layer` calling order
  `(START END DIRECTION [COUNT] [OBJECT])`, selected unambiguously by
  the symbols `up` / `down`; the legacy order keeps working.
- `tp-layer-stack-at` — the full ordered stack at one position as
  `(NAME . PROPS)` conses, hidden layers marked by a `tp-hidden`
  entry.
- Stack mutators return the number of property runs they modified
  (including `tp-merge-layers` / `tp-flatten-layers`), and layer-name
  lookups gained optional NOERROR arguments where they previously
  signaled.
- `tp-describe-layer` — interactive help-buffer description of a
  layer: storage format, arglist, stored body, expanded props,
  reactive deps, transform, owning group.

Reactive engine:

- **Layer→buffer registry**: reactive updates now visit only the
  buffers registered as showing the affected layer instead of scanning
  the whole `(buffer-list)`; every buffer-mutating write path
  registers (tp-set family, stack mutators, match/regexp appliers),
  killed buffers are pruned, and an unknown layer falls back to one
  learning full scan. `tp-reactive-layer-buffers` exposes the
  registry; `tp-reactive-track-buffer` closes the
  insert-a-propertized-string gap.
- **Minimal-diff `tp-text` re-render**: only the differing span is
  edited (insert-before-delete), so point and markers in unchanged
  text stay put and identical-text updates no longer touch the buffer
  at all (buffer-modified flag preserved).
- `tp-gc-anonymous-layers` — collects interned anonymous layers that
  no registered live buffer still shows (stack-aware: buried and
  hidden layers count as alive; string-only layers are conservatively
  kept).

Search and matching:

- `tp-regexp-set/reset/add` accept SUBEXP: properties apply to that
  capture group per match (non-participating groups contribute
  nothing); SUBEXP beyond the pattern's group count signals a clear
  error.
- `tp-match-*` / `tp-regexp-*` accept START/END bounds with
  as-if-only-that-portion semantics; reversed bounds are swapped.
- `tp-forward` / `tp-backward` / `tp-forward-do` / `tp-backward-do`
  accept PREDICATE and NOT-CURRENT, passed through to the
  text-property-search machinery; defaults keep the 0.2.0 symmetric
  equal-matching contract exactly.

Layer definitions:

- **Multi-argument parameterized layers**: `define-tp` / `define-tps`
  arglists may declare any number of parameters;
  `(LAYER ARG1 ... ARGN)` and wrapped `(LAYER (ARG1 ... ARGN))` specs
  work in `tp-set` and `tp-put-layer`; new `tp-layer-props-with-args`
  / `tp-group-props-with-args` / `tp-layer-arglist`. Wrong-arity
  calls signal clear errors naming the layer and both counts.
- Prefix-conforming aliases `tp-define-layer` / `tp-define-group` /
  `tp-define-palette` for discoverability (`C-h f tp-…`).

Core and palette:

- `tp-intervals` / `tp-intervals-map` accept an optional ABSOLUTE
  argument returning native buffer coordinates (feedable straight
  back into `tp-set`); the range-relative default is unchanged.
- `tp-palette-color` (generic theme-resolved accessor) and
  `tp-palette-has-p` consolidate the palette query surface; all
  existing query functions remain.

### Fixed

All six were found by an adversarial architecture/API review of the
new 0.3.0 code and confirmed with minimal reproductions before fixing:

- The reactive buffer registry only registered `tp-set`-family writes;
  layers applied via `tp-push-layer`, `tp-match-set`, etc. never
  re-rendered on variable updates.
- Reactive updates wrote only the rendered top layer; hidden or
  buried layers kept stale props (visible again on `tp-show-layer`).
- `tp-gc-anonymous-layers` and `tp-reactive-track-buffer` scanned only
  direct `tp-name` properties, so a layer buried in a stack (or
  hidden) could be wrongly collected / missed.
- `tp-flatten-layers` / `tp-merge-layers` rendered hidden layers'
  properties despite `tp-hide-layer`'s documented contract.
- Minimal-diff `tp-text` edits deleted before inserting, so markers at
  the suffix boundary drifted to the wrong character.
- An error escaping a reactive update could strand queued batch
  entries (now drained under `unwind-protect`; `tp-reactive-reset`
  clears the queue).

### Changed

- **Module boundaries tightened** (behavior identical under
  `(require 'tp)`): the `tp-text` handler chain moved from tp-render
  into tp-ops — partial loads now get working `tp-text` replacement —
  and `tp-with-batch-updates` moved up into tp-render; two of the four
  upward hook variables are gone
  (`tp--tp-text-handler-function`, `tp--reactive-flush-function`).
  The layer-stack storage codec and the anonymous-layer machinery now
  live in tp-layer; tp-stack's phantom dependency on tp-ops is gone;
  67 lines of dead code deleted. tp-core holds no mutable state.
- String forms of all 16 stack mutators document that they modify the
  string in place (unlike `tp-set`'s copy semantics); unifying this is
  on the 0.4 ledger.

### Deprecated

- `tp-search-forward` / `tp-search-backward` (0.3.0) — thin wrappers
  whose nil-PREDICATE default contradicts the rest of the library's
  equal-matching; use `tp-forward` / `tp-backward`, or the Emacs
  primitives for raw access.
- `tp-suffix-symbol` (0.3.0) — internal helper now private as
  `tp--suffix-symbol`; a compatibility alias remains.

### Infrastructure

- GitHub Actions CI: Emacs 28.1 / 29.4 / 30.1 matrix running
  byte-compilation with warnings-as-errors, the full ERT suite, a
  shuffled-order rerun of every test (`make test-shuffled`,
  `tp-run-shuffled.el`; `SHUFFLE_SEED=N` reproduces an order), and the
  README doctests.
- The whole tree byte-compiles with zero warnings (57 fixed:
  docstring rewraps and quoting, `defvar` declarations for reactive
  test variables, prefixed doctest counters, one impossible `eq`
  comparison corrected to `equal`).
- Autoload cookies for the interactive commands (`tp-debug-show`,
  `tp-debug-clear`, `tp-reactive-reset`, `tp-layer-reset`,
  `tp-palette-show`, `tp-clear`) and the `define-tp` / `define-tps`
  macros.
- Two doctest assertions made property-order-insensitive (Emacs 28
  prints text-property plists in a different order than 29+).

## 0.2.0 (2026-07-26)

### Architecture

- **tp.el was split into layered modules.** `(require 'tp)` still loads
  everything; nothing changes for users. Each module depends only on
  the ones before it, and the byte compiler enforces the order:

  | Module | Responsibility |
  |---|---|
  | `tp-core.el` | Intervals, plist/face merge engine, debug logging, `$var` utilities |
  | `tp-reactive.el` | Reactive dependency registry, variable watchers, batching queue |
  | `tp-layer.el` | `define-tp` / `define-tps`, layer registry and resolution |
  | `tp-ops.el` | `tp-set` / `tp-reset` / `tp-add` / `tp-get` / `tp-at` / `tp-remove` / `tp-clear` |
  | `tp-search.el` | `tp-match-*`, `tp-regexp-*`, `tp-search`, navigation |
  | `tp-render.el` | Reactive re-rendering engine (installs itself into lower modules) |
  | `tp-stack.el` | Layer stack operations (push/pop/move/merge/flatten/...) |
  | `tp-palette.el` | Light/dark color palette data |
  | `tp-builtins.el` | Built-in layers, palette gallery, display-buffer helpers |

- The library now byte-compiles cleanly (previously `define-tp`
  macro-expansion failed at compile time).
- New shared engine `tp--map-intervals`: a clipping interval walker that
  underlies region operations; property edits can no longer bleed
  outside the requested region.
- New public constant `tp-face-properties` (`'(face font-lock-face
  mouse-face)`): the property family that gets face-aware merging.

### Fixed

Core operations:

- `(require 'text-property-search)` was missing; `tp-backward` signaled
  `void-function` in batch/fresh sessions.
- `tp-remove` string form silently dropped the 3rd and later properties.
- String-form removal helpers sampled properties at position 0 and
  smeared them across the range, destroying neighboring intervals; they
  now work per-interval.
- `tp-clear` computed default bounds from the current buffer even when
  clearing a string (silent no-op or range error).
- `(tp-get STRING START END ...)` returned nil silently; it now behaves
  like the buffer region form.
- `tp-intervals` returned unclipped intervals (including negative
  offsets); it now clips to `[START, END)`.
- Region-form calls with flat prop/val arguments — `(tp-set 1 4 'face
  'bold)` — silently discarded the value and failed later; they now
  signal a clear error immediately.
- Face-family prepend semantics in `tp-add` covered only `face`; they
  now cover `font-lock-face` and `mouse-face` too.
- `tp--parse-face-list` no longer invents a `(:key nil)` pair for a
  trailing bare keyword.

Built-ins and palette:

- Emacs 28.1 compatibility restored (`plistp` is Emacs 29+; a compat
  shim is used, and `subr-x` is required where needed).
- `tp-pop-to-buffer` / `tp-switch-to-buffer` no longer bind `q` in the
  shared major-mode keymap (a buffer-local minor-mode keymap is used)
  and no longer capture a `buffer` variable from the caller.
- `tp-link` resolved its palette color once at load time; the color is
  now resolved at application time, so theme switches are honored.
- `define-tp-palette` no longer generates per-palette defvars;
  `tp-palette-alist` is the single source of truth and palette
  redefinition takes effect immediately.
- `tp-headline` emitted invalid `(:height nil)` for integer heights.
- `tp-space` now produces the documented pixel `(space :width (N))`
  spec.
- `tp-parse-color` accepts one-sided cons colors like `("white" . nil)`.

Layer definitions (tp-layer):

- Parameterized `define-tps` groups: the documented format returned nil
  props via `tp-group-props-with-arg`; all documented element shapes now
  resolve correctly.
- Cyclic layer references signal a clear error naming the cycle
  (previously crashed with `excessive-lisp-nesting`); diamond-shaped
  reuse is not a false positive.
- `define-tp` errors at macro-expansion time when extra body forms are
  present (previously silently discarded all but the first).
- `$`-symbols in parameterized layer bodies resolve to their variables'
  current values at evaluation time (previously leaked literally into
  the output props); parameterized layers remain non-reactive, and the
  choice is documented.
- `tp-layer-props` / `tp-group-props` and their `-with-arg` variants
  return copies; mutating a returned plist can no longer corrupt the
  registry.
- `:transform` in `define-tps` group elements is honored (was silently
  dropped).
- Group redefinition and `tp-undefine-group` clean up the layers the
  group generated, including their reactive deps and transforms
  (previously orphaned).
- The group-element parser errors on unknown keywords instead of
  advancing by one and re-reading a value as a key.
- Anonymous reactive layers are interned: an `equal` `$var` props spec
  reuses the existing registry entry instead of minting a new one on
  every `tp-set` (unbounded leak fixed).

Layer stacks (tp-stack):

- All stack mutators were rewritten onto a shared clipped region walker;
  region ops no longer alter text outside `[START, END)`, and
  `tp-put-layer` is region-local instead of switching behavior on
  whole-object emptiness.
- The documented inline-plist spec (`(face bold ...)`) and
  list-of-layer-names spec (`'(layer-a layer-b)`) for `tp-put-layer`
  work (previously errored), handled at the call site.
- `tp-region-layer-props` no longer double-offsets string positions.
- `tp-merge-layers` / `tp-flatten-layers` no longer drop explicitly-nil
  values (presence is checked with `plist-member`).
- Single-layer stacks no longer carry a garbage `(tp-layers nil)`
  property, and its absence is tolerated everywhere.
- `tp-layer-top` respects the requested region instead of reading only
  the first interval.

Search and navigation (tp-search):

- `tp-backward` buffer paths passed no predicate to
  `text-property-search-backward`, so matching was inverted relative to
  `tp-forward`; backward now mirrors forward's equal-matching
  semantics. The legacy test that codified the inverted behavior
  (`tp-test-backward`) was updated to the symmetric contract.
- Empty and zero-width patterns no longer loop forever in the
  match/regexp apply engines.
- Length-changing replacements work in buffers in `tp-forward-do` /
  `tp-backward-do` / `tp-search-map` (previously signaled
  `args-out-of-range` via `store-substring`). On strings — which cannot
  change length in place — a length-changing replacement signals a
  clear error instead of silently truncating or leaving residue;
  same-length string replacements are unchanged.
- `tp-search-map` with a non-current buffer OBJECT operates on that
  buffer (previously read and mutated the current buffer) and no longer
  corrupts buffers on length-changing replacements.
- `tp-match-add` buffer path uses face-family-aware merging like the
  string path, so existing faces are preserved.
- `tp-search-map` can remove properties on strings (nil-props ranges
  were previously skipped).
- The triplicated ~38-line replacement lambda was extracted into one
  shared helper.
- `tp-forward-do` / `tp-backward-do` shortfall is now all-or-nothing on
  both paths: TIMES targets the TIMES-th match specifically, so when
  fewer matches exist nothing is applied and the available count is
  returned. String paths previously acted on the last available match —
  the wrong target; the two legacy tests codifying that
  (`tp-test-forward-do-on-string-with-range` and its backward twin)
  were updated.

Reactive rendering (tp-reactive / tp-render):

- Sub-region `tp-text` on a string no longer discards the rest of the
  string.
- Computed-variable updates deep-merge resolved props with the layer
  definition, preserving sibling static attributes.
- Reactive refresh replaces the re-rendered layer's own property keys
  instead of accumulating (bold→italic no longer yields
  `(italic bold)`), while preserving other layers' properties.
- `setq-local` re-renders the buffer without leaking buffer-local
  values into the global layer definition.
- Reactive `tp-text` replacement preserves unrelated existing
  properties.
- Computed values of nil propagate (nil was conflated with the error
  sentinel).
- Variable-watcher reentrancy: nested `set` calls inside the update
  path queue their re-render through the batch queue instead of
  recursing.
- Batched updates union their WHERE and tp-text flags at flush time
  instead of freezing the first change's.
- Reactive strings keep per-interval props on re-render (previously
  only position-0 props survived and were smeared).
- `:transform` applies on the first render too, not only on updates.

Test infrastructure:

- The test fixture now tears down with `unwind-protect` and resets all
  registries including `tp-layer-transforms` (previously leaked across
  tests); the suite passes in randomized order.
- `tp-tests.el` header and `provide` renamed to match its file name.

### Added

- `tp-member`: like `tp-at`, but distinguishes "property present with
  value nil" from "property absent" (plist-member-style result).
- `Makefile` with `test` / `doctest` / `compile` / `clean` targets.
- `tp-doctest.el`: executable documentation tests — 63 assertions
  reproducing README examples and comparing against their exact
  documented outputs (`make doctest`).
- Per-module regression test suites: `tp-core-tests.el`,
  `tp-ops-tests.el`, `tp-builtins-tests.el`, `tp-layer-tests.el`,
  `tp-stack-tests.el`, `tp-search-tests.el`, `tp-render-tests.el` —
  the combined suite grew from 280 to 439 tests.

### Changed

- License clarified to GPLv3+ in file headers, matching the shipped
  LICENSE file (headers previously said v2+).

## 0.1.0

Initial release (monolithic tp.el).