token_lock.hpp File Reference

Token lock-to-source via DESIGN.md export. More...

#include <optional>
#include <string>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::view::TokenTarget
	A tweak classified as targeting a design token. More...
struct	pulp::view::TokenLockResult
	Outcome of a lock_token_in_designmd call. More...

Namespaces
namespace	pulp
namespace	pulp::view
	Hover-cursor tracking for platform window hosts.

Enumerations
enum class	pulp::view::TokenGroup { pulp::view::colors , pulp::view::spacing , pulp::view::rounded , pulp::view::typography }
	The four canonical DESIGN.md frontmatter token groups this engine can lock into. More...

Functions
const char *	pulp::view::token_group_key (TokenGroup group)
	Stringify a TokenGroup as its DESIGN.md frontmatter key.
std::optional< TokenTarget >	pulp::view::classify_token_tweak (const std::string &anchor_id, const std::string &property_path)
	Classify a tweak as token-typed or not.
TokenLockResult	pulp::view::lock_token_in_designmd (const std::string &markdown, const TokenTarget &target, const std::string &new_value)
	Lock a single token tweak back into DESIGN.md text.
TokenLockResult	pulp::view::lock_token_in_designmd (const std::string &markdown, const std::string &anchor_id, const std::string &property_path, const std::string &new_value)
	Convenience overload: classify + lock in one call.

Detailed Description

Token lock-to-source via DESIGN.md export.

When a user makes an inspector tweak that corresponds to a design token — a palette color, a spacing-scale step, a corner radius, a typography field — "locking" that tweak should write the corrected value back into the project's DESIGN.md, so the next re-import from the design tool (Figma / Stitch / v0 / Pencil / Claude) picks up the fixed token rather than re-introducing the stale one.

This is the token-level sibling of generated-source locking and authored JSX/TSX locking. Those mechanisms rewrite element source; this one rewrites a single token value in the YAML frontmatter of DESIGN.md.

Design rationale — why a surgical text rewrite, not export_designmd: export_designmd(Theme, ...) (design_export.hpp) re-emits a whole DESIGN.md from a Theme. That would be the wrong tool here: it cannot preserve the author's prose sections, comment placement, key ordering, or original dimension spelling ("1.5rem" vs "24px"). Locking ONE token must not reflow the entire file. So lock_token_in_designmd instead parses the frontmatter to locate the token, then performs a minimal value-only edit on the original text — every other byte of the file (prose, comments, ordering, indentation) is preserved.

Conservatism contract: if the token cannot be located unambiguously in DESIGN.md the lock FAILS with a clear message rather than guessing. A failed lock leaves DESIGN.md byte-identical and the tweak untouched in pulp-tweaks.json.