tp/CHANGELOG.md

Changelog

All notable changes to the tp library are documented here.

2.0.0 (Unreleased)

Added

• A standalone retained surface runtime with pure defensive plans, prepare-scoped stable objects, keyed/positional reconciliation, content and properties capabilities, marker-backed range anchors, object/mount indexes, scoped updates, opaque client state, generic reports, and lifecycle cleanup.
• Exact signal-to-binding and binding-to-binding dependency tracking with conditional rewiring, equality cutoffs, batched transactions, nested-write stabilization, owner disposal, buffer-scoped sources, variable adapters, cycle paths, and public structural counters.
• Atomic single- and multi-surface publication with candidate source values, prepare-all/publish-all ordering, explicit property journals, rollback-capable transaction participants, observer isolation, and authoritative kill-buffer cleanup.
• Transaction protocol v2: transaction-scoped publication batches, structured participants, bounded opaque final-accept markers using the closed tp-vector-slots/v1 primitive, immutable tagged outcomes, and one live writer.
• tp-runtime-manifest, advertising tp-transaction-protocol-v2 and package version 2.0.0.
• Public tp-transaction-participate-v2 registration for cross-package structured participants.
• Native property policies and contribution composition with explicit nil/absence, normalization, validation, equality, merge, projection, named direct styles, and explicit tp-computed value sources.
• tp-propertize, tp-apply, and tp-watch as the one-shot string, one-shot buffer-range, and reactive existing-text conveniences over the same direct property/surface core.
• Retained logical objects with tp-object-retain and tp-object-attach-fragment, allowing one object to own multiple disjoint physical fragments without placing handles or positions in plans.
• Standalone examples for static properties, reactive status decoration, retained dashboards, and editable diagnostics.

Changed

• Structured publication batches own the single live surface-entry loop, participant stage/precommit/commit vector, and candidate-bound final accept.
• Package metadata now identifies the v2-only breaking transaction contract.
• define-tp and define-tps now define static or parameterized direct declaration recipes. Applying a recipe produces ordinary properties and never publishes runtime identity metadata.
• TP is no longer a CSS engine. Selector, stylesheet, specificity, origin/importance, cascade layer, CSS-wide value, custom property, winner, and provenance behavior belongs to the independent ECSS package.
• Function-valued properties are always literal. Only values wrapped by tp-computed execute and participate in dependency collection.
• Runtime identity and provenance live exclusively in side state. Normal updates follow source to binding to object to marker-backed mount without scanning buffers or displayed text.
• Package documentation, API semantics, architecture, doctests, and tests now describe the single TP 1.0 runtime rather than the transitional 0.3 managed model.

Removed

• The public tp-transaction-participate v1 facade. Replace (tp-transaction-participate KEY PUBLISH ROLLBACK) with (tp-transaction-participate-v2 :key KEY :stage PUBLISH :rollback ROLLBACK).

• The v1 publication writer, execution-route kill switch, artifact-mode switch, and their runtime manifest claims.

• tp-render.el, tp-stack.el, the scan-driven renderer, layer-to-buffer registry, and duplicate managed transaction path.

• Managed stack mutation, attach/detach, diagnostics, and lifecycle APIs that depended on inline stack storage.

• tp-text, $variable declaration syntax, automatic layer refresh, and character-level tp-name/tp-layers/tp-meta runtime storage.

• TP-owned CSS selector/stylesheet/cascade APIs and compatibility aliases.

• The unused Dash runtime dependency.

• Unused global theme lifecycle advice and managed-refresh bookkeeping from the deleted renderer.

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).