jsx_lock.hpp File Reference

Lock-to-source support for hand-authored JSX/TSX. More...

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

Go to the source code of this file.

Classes
struct	pulp::view::JsxLockTweak
	A single tweak to promote into authored JSX/TSX source. More...
struct	pulp::view::JsxLockResult
	Result of locking one tweak into an authored JSX/TSX source string. More...

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

Enumerations
enum class	pulp::view::JsxLockStatus {   pulp::view::patched , pulp::view::already_current , pulp::view::anchor_not_found , pulp::view::anchor_ambiguous ,   pulp::view::unsupported_property , pulp::view::too_dynamic }
	Outcome status for a single JSX/TSX lock attempt. More...

Functions
std::optional< std::string >	pulp::view::jsx_lock_property_to_key (const std::string &property_path)
	Map a dotted tweak property_path (paint.backgroundColor, style.width, layout.padding, a bare width, …) to the camelCase JSX style / prop key the engine looks for in style={{…}} or as a bare attribute.
bool	pulp::view::is_authored_jsx_source (const std::string &source)
	Heuristic guard: does source look like hand-authored JSX/TSX (as opposed to a Pulp-generated web-compat artifact)?
JsxLockResult	pulp::view::jsx_lock_tweak_into_source (const std::string &source, const JsxLockTweak &tweak)
	Locate the JSX element carrying data-pulp-anchor="<tweak.anchor_id>" in an authored JSX/TSX source string and surgically rewrite the literal value of the prop named by tweak.property_path so it carries tweak.value.
std::vector< JsxLockResult >	pulp::view::jsx_lock_tweaks_into_source (const std::string &source, const std::vector< JsxLockTweak > &tweaks)
	Lock several tweaks into the same authored source in one pass.

Detailed Description

Lock-to-source support for hand-authored JSX/TSX.

The inspector's direct-manipulation edits land in a tweaks layer (pulp-tweaks.json, keyed by stable_anchor_id). "Lock to source" is the explicit, opt-in promotion of a tweak back into the authored source so the change survives a fresh re-import.

Where lock_to_source.hpp rewrites the generated web-compat JS that pulp import-design emits, this header handles the other half of the lock-to-source contract: the user is running a live React bundle built from a hand-authored JSX/TSX file (pulp import-design --from jsx, --execute-bundle). That JSX/TSX is the user's own source — there is no generated artifact to rewrite.

How an authored element is located

At JSX-transform time an element-instrumentation pass injects a data-pulp-anchor="<stable_anchor_id>" attribute onto each authored element (the JS-side instrumentation is a separate deliverable; this engine only consumes the marker). At lock time the engine finds the opening JSX tag carrying data-pulp-anchor="<anchor_id>" and patches the targeted prop.

Patch strategy — surgical, not a full AST re-emit

The lock-to-source engines deliberately do minimal rewrites: they locate the exact span that owns the value and rewrite only that span, preserving every other byte (prose, comments, formatting, key order). This is NOT a general JSX-to-JSX AST printer. It performs a tightly-scoped, anchored text edit:

• style={{ padding: 8, background: '#888' }} — the engine finds the matching object property inside the inline-style literal and rewrites just that property's value.
• width={80} / width="80" / color="#888" — a bare prop whose value is a literal: the engine rewrites the literal in place.

Anything the engine cannot patch safely and unambiguously — a spread (style={{ ...base }}), a computed key, a non-literal value (padding={gap * 2}, color={theme.fg}), a className-driven style, a duplicate anchor — is reported as a typed failure so the caller leaves the tweak in the sidecar with a "too dynamic to lock" message.

Conservatism contract

If the target element or prop cannot be located unambiguously, the lock FAILS and the source is returned byte-identical. The engine never guesses and never emits a malformed edit. It is a pure function: no filesystem I/O, never throws.