Would an opt-in declaration source-provenance API be in scope?

[YT-TechDev]

Hi,

I am evaluating cssparser for source-backed developer tooling that needs exact
zero-based, half-open UTF-8 byte ranges for CSS declarations while preserving the
existing full-stylesheet and RuleBodyParser lifecycle.

For example:

a { c\6F lor/**/: red !/**/Im\70 ortant; }

The decoded property name is color, but the authored property-name spelling is
c\6F lor. Its exact raw endpoint cannot be reconstructed safely from the
decoded identifier length.

In the current RuleBodyParser declaration path, the parser records the
declaration start, consumes the property-name Ident and the colon, and then
calls DeclarationParser::parse_value. The callback receives the decoded name,
a parser positioned after the colon, and the declaration-start state. The
high-level path also finalizes through parse_until_after, so it does not expose
whether the declaration ended with an authored semicolon, the end of the current
block, or the end of the input.

Recovering these boundaries downstream by searching the retained source,
resetting and replaying the parser, reparsing a fragment, or introducing another
tokenizer would duplicate parser behavior and could diverge around escapes,
comments, malformed input, and declaration-versus-qualified-rule retry.

Would an additive, opt-in public capability for declaration source provenance be
considered in scope for cssparser?

The coherent capability I am trying to validate would allow an opt-in consumer
to obtain, for a declaration that ultimately commits:

• parser-owned raw boundaries for the property name and colon;
• value-boundary checkpoints captured from the active Parser, while property
  and descriptor grammar remains downstream;
• an exact raw range from a provenance-aware equivalent of parse_important
  when the consumer accepts that annotation in the current context;
• the termination kind and range, distinguishing an authored semicolon, block
  end, and input end; and
• no committed declaration provenance when a failed declaration attempt is
  retried and accepted as a qualified rule.

I am not committed to a particular API shape or to implementing this as one
large change. Possible directions could include a structured parse context,
additive lifecycle observations, parser-owned result metadata, or a separate
source-aware path that shares the existing parsing control flow.

The intended constraints are:

• preserve existing declaration recognition, nesting retry, and error behavior;
• keep property and descriptor value grammar downstream;
• avoid changing existing required trait methods or iterator item types when an
  additive design is practical;
• do not accept arbitrary downstream offsets as parser-authenticated evidence;
• avoid source searching, replay, fragment reparsing, a second tokenizer, or
  exposure of unstable tokenizer internals;
• avoid mandatory parser-state growth or hot-path cost for consumers that do not
  request provenance unless measurement justifies it; and
• avoid requiring a permanent downstream fork.

Before preparing a prototype, I would appreciate guidance on:

1. whether this capability belongs in cssparser;
2. whether maintainers would prefer an Issue, a small prototype, or a draft Pull
   Request first; and
3. whether an initial bounded prototype should begin with parser-owned prefix and
   termination boundaries while documenting the coherent lifecycle, or should
   cover the committed declaration envelope including consumer-assisted value
   and priority observations from the start.

I can prepare a bounded API comparison, focused test cases, compatibility checks,
and a representative downstream usage example after receiving direction.

Thank you.

[nicoburns]

I can't comment as to whether this would be appropriate for cssparser, but wanted to point you towards https://csskit.rs as an existing developer tooling focussed CSS parser implementation in Rust.