marker: stylex.when.* specificity + derive types from runtime functions (#5)

[dogmar]

Closes klink-ing/bearbones#5.

Summary

Two layered changes:

1. Marker selectors mirror StyleX's when.* specificity contract — every relation wraps the marker observation in :where(...) so the observed marker contributes zero specificity. The styled rule lands at (0, 1, 0), same as a plain utility, so toggling a marker doesn't unconditionally beat a utility class. Surface expanded from 3 relations to StyleX's 5: ancestor, descendant, siblingBefore, siblingAfter, siblingAny. Selector templates centralized in a single RELATION_SELECTOR_ENTRIES table that drives both runtime and type emit.

2. Marker types are fully derived from runtime function return types — every literal in the patched css.d.ts either comes from ReturnType<typeof fn<...>> or from a single-source typed map. No hand-maintained CSS in the type emit.

Selector contract

Relation	Lowered selector	Specificity
ancestor	:where(${m}) &	0,1,0
descendant	&:where(:has(${m}))	0,1,0
siblingBefore	:where(${m}) ~ &	0,1,0
siblingAfter	&:where(:has(~ ${m}))	0,1,0
siblingAny	&:where(:has(~ ${m})), :where(${m}) ~ &	0,1,0

m is the user's condition value with every & substituted for .bearbones-marker-<id>_<hash>. The &-prefixed branch comes first in siblingAny so the literal type satisfies Panda's AnySelector.

How types are derived

The patched css.d.ts now reads:

import type {
  composeRelationSelectors,
  markerAnchor,
  markerAnchorClass,
  substituteAmp,
} from '@bearbones/vite';

type BearbonesMarkerAnchor<Id extends string> = ReturnType<typeof markerAnchor<Id, "<HASH>">>;

type BearbonesObserver<Id extends string, Cond extends string> = ReturnType<
  typeof substituteAmp<Cond, BearbonesMarkerAnchor<Id>>
>;

export interface BearbonesMarkerBuilder<Id extends string, Cond extends string> {
  readonly is: ReturnType<typeof composeRelationSelectors<BearbonesObserver<Id, Cond>>>;
}

type BearbonesMarkerConditions = {
  readonly "hover": "&:is(:hover, [data-hover])";
  readonly "focusVisible": "&:is(:focus-visible, [data-focus-visible])";
  /* …one entry per condition the host has registered */
};

type BearbonesMarkerShortcuts<Id extends string> = {
  readonly [K in keyof BearbonesMarkerConditions as `_${K & string}`]:
    BearbonesMarkerBuilder<Id, BearbonesMarkerConditions[K]>;
};

export interface BearbonesMarker<Id extends string = string>
  extends BearbonesMarkerShortcuts<Id> {
  readonly anchor: ReturnType<typeof markerAnchorClass<Id, string>>;
  <C extends string>(condValue: C): BearbonesMarkerBuilder<Id, C>;
}

So cardMarker._hover.is.ancestor evaluates at the type level to the exact runtime selector — modulo the build-time SHA1 hash, which the type substitutes with the literal placeholder <HASH> (verified by eight pinned literal-type assertions in css-typing.ts).

Repo changes

Selector pipeline (packages/bearbones-vite)

• marker-registry.ts: introduces RELATION_SELECTOR_ENTRIES (the segment table), RELATION_SELECTORS (record form), MARKER_RELATIONS (tuple), RelationSelectors<T>, composeRelationSelectors, applyRelationSelector, markerAnchor, markerAnchorClass. buildRelationSelector now pipes through substituteAmp + applyRelationSelector so runtime mirrors the type-level derivation step-by-step.
• transform.ts: runtime __bearbones_relations helper is generated at build time from RELATION_SELECTORS (sentinel-split + JS concat), so build-time and runtime stay byte-identical without a hand-maintained duplicate. renderMarkerRecord iterates MARKER_RELATIONS.
• codegen-patch.ts: renderMarkerTypes emits the four runtime-function-derived alias types above, plus BearbonesMarkerConditions (single source of truth for condition strings) and BearbonesMarkerShortcuts (mapped type that synthesizes one _<name> shortcut per entry).

New package: @bearbones/utils

Private workspace package (never publishes) holding the generic TS utilities the marker pipeline depends on:

• Type-level: InterpolateParts, EntryNames, SubstituteAmp
• Runtime: substituteAmp, deepAssign, shortHash

@bearbones/vite declares @bearbones/utils under devDependencies and inlines its source/types into the published dist via tsdown's deps.alwaysBundle. vite.config.ts declares the build task with dependsOn: ["@bearbones/utils#build"] so vp run -r build orders correctly.

Specificity test

marker-registry.test.ts has a real specificity-contract assertion that runs every emitted selector through @bramus/specificity (canonical CSS Specificity Calculator), substituting & with a sentinel class, asserting (0, 1, 0) per comma-branch.

Other

• Stable dts pipeline — dropped @typescript/native-preview (experimental tsgo) for reliability.
• Marker chains accept arbitrary condition values verbatim; & is required and substituted into the relation observer.
• Demo / __type-tests__/css-typing.ts updated to use siblingAny and pin the literal-string evaluation of every relation.

Test plan

• vp check clean
• vp run -r test — 60/60 in @bearbones/vite, 17/17 in @bearbones/utils
• vp run -r build end-to-end — utils → preset → vite → website panda+tsc+vite production bundle
• Eight pinned literal-type assertions in css-typing.ts verify the cardMarker(...).is.<relation> evaluation matches the runtime selector

Files

• packages/utils/ — new private workspace package
• packages/bearbones-vite/src/marker-registry.ts — RELATION_SELECTOR_ENTRIES + helpers
• packages/bearbones-vite/src/transform.ts — runtime helper derived from RELATION_SELECTORS
• packages/bearbones-vite/src/codegen-patch.ts — BearbonesMarkerConditions + BearbonesMarkerShortcuts mapped emit
• packages/bearbones-vite/tests/marker-registry.test.ts — specificity contract + per-relation assertions
• packages/bearbones-vite/tests/codegen-patch.test.ts — single-occurrence + derivation assertions
• apps/website/src/__type-tests__/css-typing.ts — pinned literal-type assertions
• apps/website/src/Demo.tsx — siblingAny showcase + missing-& fix
• docs/superpowers/specs/2026-05-02-marker-stylex-specificity-design.md — design spec

🤖 Generated with Claude Code