@shapeshift-labs/frontier-lang-css 0.1.14 → 0.1.15

package/README.md

@@ -232,11 +232,11 @@ const merge = safeMergeCssSource({
 });
 ```
 
-`sourceMap.mappings` links emitted rule blocks back to Frontier Lang semantic node ids. `createCssSemanticMergeEvidence` records selectors, specificity, declarations, custom properties, `var()` fallback references, animation/keyframe links, font-face links, URL asset references, cascade keys, statement-form at-rules, block-form runtime at-rules, CSS Modules exports, ICSS edges, scoped cascade graph proof hashes, source spans, stable hashes, and fail-closed proof gaps for cascade/render-sensitive CSS surfaces. `safeMergeCssSource` admits independent declaration edits by cascade key, including existing scoped `@media` / `@supports` / `@container` / `@layer` declarations when a scoped cascade graph proof hash is supplied, carries source-bound dependency graph evidence into the merge result, blocks dependency-affecting declaration edits unless an exact source-bound dependency graph proof is supplied, blocks parallel edits whose CSS shorthand expansions overlap a longhand or sub-shorthand, preserves unchanged statement-form at-rules such as `@layer reset, components;`, preserves unchanged block-form runtime at-rules such as `@keyframes` and `@font-face`, and for `.module.css` files it classifies exported local classes, `composes`, and ICSS import/export records as explicit merge contracts. Cascade-sensitive source-shape changes still block by default, but a host can attach a `css-source-bound-cascade-runtime-proof` / `css-cascade-runtime-proof` that is bound to the exact source path, reason, side, shape key, and base/worker/head/output source hashes to admit that specific change.
+`sourceMap.mappings` links emitted rule blocks back to Frontier Lang semantic node ids. `createCssSemanticMergeEvidence` records selectors, specificity, declarations, custom properties, `var()` fallback references, animation/keyframe links, font-face links, URL asset references, cascade keys, statement-form at-rules, block-form runtime at-rules, CSS Modules exports, ICSS edges, scoped cascade graph proof hashes, source spans, stable hashes, and fail-closed proof gaps for cascade/render-sensitive CSS surfaces. `safeMergeCssSource` admits independent declaration edits by cascade key, including existing scoped `@media` / `@supports` / `@container` / `@layer` declarations when a scoped cascade graph proof hash is supplied, carries source-bound dependency graph evidence into the merge result, blocks dependency-affecting declaration edits unless an exact source-bound dependency graph proof is supplied, blocks selector-target rebases unless the host supplies a source-bound selector target graph hash and the parser proves selector specificity is invariant, blocks parallel edits whose CSS shorthand expansions overlap a longhand or sub-shorthand, preserves unchanged statement-form at-rules such as `@layer reset, components;`, preserves unchanged block-form runtime at-rules such as `@keyframes` and `@font-face`, and for `.module.css` files it classifies exported local classes, `composes`, and ICSS import/export records as explicit merge contracts. Cascade-sensitive source-shape changes still block by default, but a host can attach a `css-source-bound-cascade-runtime-proof` / `css-cascade-runtime-proof` that is bound to the exact source path, reason, side, shape key, and base/worker/head/output source hashes to admit that specific change.
 
 ## Support Boundary
 
 - Ready evidence: style rules, selectors, specificity, declarations, source-bound dependency graph hashes for custom properties, `var()` fallbacks, animations/keyframes, font faces, and URL assets, statement-form at-rules, block-form runtime at-rules, CSS Modules local exports, generated class-name map coverage, JS/TS use-site graph hashes, composition graph hashes, ICSS graph hashes, scoped cascade graph hashes, source-bound cascade runtime proofs, source spans, stable hashes.
-- Safe merge: independent declarations with non-overlapping cascade keys, non-overlapping shorthand expansion sets, and no changed dependency graph surface; unchanged statement-form at-rules and unchanged block-form runtime at-rules preserved in canonical output; existing scoped declaration edits when scoped cascade graph proof is supplied; dependency-affecting declaration edits only when an exact source-bound dependency graph proof is supplied; source-shape/cascade-sensitive edits only when an exact source-bound cascade runtime proof is supplied; explicit CSS Modules export additions/deletions when generated class-name and JS/TS use-site graph proof is supplied; composition edits when composition graph proof is supplied; ICSS edits when ICSS graph proof is supplied. Output is a canonical CSS render and not a byte/trivia-preserving claim.
+- Safe merge: independent declarations with non-overlapping cascade keys, non-overlapping shorthand expansion sets, and no changed dependency graph surface; unchanged statement-form at-rules and unchanged block-form runtime at-rules preserved in canonical output; existing scoped declaration edits when scoped cascade graph proof is supplied; dependency-affecting declaration edits only when an exact source-bound dependency graph proof is supplied; selector-target rebases only when a matching selector target graph hash is supplied and before/after selector specificity is identical; source-shape/cascade-sensitive edits only when an exact source-bound cascade runtime proof is supplied; explicit CSS Modules export additions/deletions when generated class-name and JS/TS use-site graph proof is supplied; composition edits when composition graph proof is supplied; ICSS edits when ICSS graph proof is supplied. Output is a canonical CSS render and not a byte/trivia-preserving claim.
 - Review-only gaps: incomplete generated class-name maps, unproved dependency graph changes, unproved CSS Modules use-site graphs, unproved composition or ICSS graphs, shorthand value expansion/equivalence beyond known affected-property overlap checks, statement-form at-rule order/condition changes, one-sided or structurally changed scoped cascade under `@media` / `@supports` / `@container` / `@layer`, changed runtime blocks such as `@keyframes`, `@font-face`, `@page`, and `@property`, browser layout and render equivalence.
 - Claims: dependency graph evidence is an admission/review signal only unless an exact source-bound dependency graph proof admits the changed dependency surface; `autoMergeClaim`, `semanticEquivalenceClaim`, and `browserRenderEquivalenceClaim` remain false. `browserCascadeEquivalenceClaim` is only true on a safe-merge result when a source-bound cascade runtime proof admits the specific cascade-sensitive source-shape change.

package/dist/index.d.ts

@@ -273,15 +273,15 @@ export interface CssSafeMergeSelectorTargetSideEvidence {
 export interface CssSafeMergeSelectorMove {
   readonly side: string; readonly property: string; readonly beforeRuleKey: string; readonly afterRuleKey: string;
   readonly beforeSelectors?: readonly string[]; readonly afterSelectors?: readonly string[]; readonly beforeScopes?: readonly string[]; readonly afterScopes?: readonly string[];
-  readonly declarationHash: string; readonly beforeSelectorTargetGraphHash?: string; readonly afterSelectorTargetGraphHash?: string; readonly selectorTargetGraphHashPresent: boolean;
+  readonly beforeSpecificity?: readonly (readonly number[])[]; readonly afterSpecificity?: readonly (readonly number[])[]; readonly specificityInvariant: boolean; readonly declarationHash: string; readonly beforeSelectorTargetGraphHash?: string; readonly afterSelectorTargetGraphHash?: string; readonly selectorTargetGraphHashPresent: boolean;
 }
 
 export interface CssSafeMergeSelectorTargetRebaseProof {
-  readonly kind: 'css-selector-target-rebase'; readonly side: string; readonly fromRuleKey: string; readonly toRuleKey: string; readonly property: string; readonly cascadeKey: string;
+  readonly kind: 'css-selector-target-rebase'; readonly side: string; readonly fromRuleKey: string; readonly toRuleKey: string; readonly property: string; readonly cascadeKey: string; readonly selectorTargetGraphHash?: string; readonly specificityInvariant: true; readonly beforeSpecificity?: readonly (readonly number[])[]; readonly afterSpecificity?: readonly (readonly number[])[];
 }
 
 export interface CssSelectorTargetEquivalence {
-  readonly fromRuleKey?: string; readonly toRuleKey?: string; readonly fromSelectors?: readonly string[]; readonly toSelectors?: readonly string[]; readonly graphHash?: string;
+  readonly sourcePath?: string; readonly fromRuleKey?: string; readonly toRuleKey?: string; readonly fromSelectors?: readonly string[]; readonly toSelectors?: readonly string[]; readonly fromSpecificity?: readonly (readonly number[])[]; readonly toSpecificity?: readonly (readonly number[])[]; readonly graphHash?: string;
 }
 
 export interface CssSafeMergeInput {

package/dist/semantic-merge-selector-targets.js

@@ -45,6 +45,9 @@ function selectorTargetMoves(changes, side) {
       afterSelectors: addition.after.selectors,
       beforeScopes: deletion.before.scopes,
       afterScopes: addition.after.scopes,
+      beforeSpecificity: deletion.before.specificity,
+      afterSpecificity: addition.after.specificity,
+      specificityInvariant: specificityListKey(deletion.before.specificity) === specificityListKey(addition.after.specificity),
       declarationHash: addition.after.declarationHash,
       beforeSelectorTargetGraphHash: deletion.before.selectorTargetGraphHash,
       afterSelectorTargetGraphHash: addition.after.selectorTargetGraphHash,
@@ -73,7 +76,7 @@ function selectorTargetMoveSidePlan(id, sourcePath, moves, oppositeMoves, opposi
     for (let index = 0; index < oppositeChanges.length; index += 1) {
       const change = oppositeChanges[index];
       if (!selectorMoveTouchesChange(move, change)) continue;
-      if (canRebaseChange(move, change, options)) {
+      if (canRebaseChange(move, change, options, sourcePath)) {
         const rebased = rebaseChangeToSelectorMove(change, move);
         oppositeChanges[index] = rebased.change;
         rebaseProofs.push(rebased.proof);
@@ -83,16 +86,19 @@ function selectorTargetMoveSidePlan(id, sourcePath, moves, oppositeMoves, opposi
   return { conflicts, rebaseProofs };
 }
 
-function canRebaseChange(move, change, options) {
-  return change.kind === 'add' && change.after && hasSelectorTargetEquivalence(move, options);
+function canRebaseChange(move, change, options, sourcePath) {
+  return change.kind === 'add' && change.after && hasSelectorTargetEquivalence(move, options, sourcePath);
 }
 
-function hasSelectorTargetEquivalence(move, options) {
+function hasSelectorTargetEquivalence(move, options, sourcePath) {
+  if (!move.specificityInvariant) return false;
   return (options.selectorTargetEquivalences ?? []).some((entry) => {
+    const sourceMatches = !entry.sourcePath || entry.sourcePath === sourcePath;
     const ruleKeysMatch = entry.fromRuleKey === move.beforeRuleKey && entry.toRuleKey === move.afterRuleKey;
     const selectorsMatch = selectorListKey(entry.fromSelectors) === selectorListKey(move.beforeSelectors) && selectorListKey(entry.toSelectors) === selectorListKey(move.afterSelectors);
-    const graphMatches = !entry.graphHash || entry.graphHash === move.beforeSelectorTargetGraphHash || entry.graphHash === move.afterSelectorTargetGraphHash;
-    return graphMatches && (ruleKeysMatch || selectorsMatch);
+    const graphMatches = Boolean(entry.graphHash && entry.graphHash === move.beforeSelectorTargetGraphHash && entry.graphHash === move.afterSelectorTargetGraphHash);
+    const specificityMatches = (!entry.fromSpecificity || specificityListKey(entry.fromSpecificity) === specificityListKey(move.beforeSpecificity)) && (!entry.toSpecificity || specificityListKey(entry.toSpecificity) === specificityListKey(move.afterSpecificity));
+    return sourceMatches && graphMatches && specificityMatches && (ruleKeysMatch || selectorsMatch);
   });
 }
 
@@ -100,7 +106,7 @@ function rebaseChangeToSelectorMove(change, move) {
   const after = { ...change.after, ruleKey: move.afterRuleKey, selectors: move.afterSelectors, scopes: move.afterScopes ?? [], key: cascadeKey(move.afterScopes, move.afterSelectors, change.after.property), rebasedFromRuleKey: move.beforeRuleKey };
   return {
     change: { ...change, key: after.key, after },
-    proof: { kind: 'css-selector-target-rebase', side: change.side, fromRuleKey: move.beforeRuleKey, toRuleKey: move.afterRuleKey, property: change.after.property, cascadeKey: after.key }
+    proof: { kind: 'css-selector-target-rebase', side: change.side, fromRuleKey: move.beforeRuleKey, toRuleKey: move.afterRuleKey, property: change.after.property, cascadeKey: after.key, selectorTargetGraphHash: move.afterSelectorTargetGraphHash, specificityInvariant: true, beforeSpecificity: move.beforeSpecificity, afterSpecificity: move.afterSpecificity }
   };
 }
 
@@ -134,6 +140,7 @@ function sameSelectorMove(left, right) {
 
 function cascadeKey(scopes = [], selectors = [], property) { return [...scopes, selectors.join(','), property].join('::'); }
 function selectorListKey(value = []) { return Array.isArray(value) ? value.join(',') : undefined; }
+function specificityListKey(value = []) { return Array.isArray(value) ? value.map((item) => Array.isArray(item) ? item.join(',') : '').join('|') : undefined; }
 function changeDetails(change) { return { kind: change.kind, property: (change.after ?? change.before)?.property, value: change.after?.value, important: change.after?.important }; }
 
 export { mergeSelectorTargetEvidence, planSelectorTargetRebase };

package/dist/semantic-merge.js

@@ -101,7 +101,7 @@ function declarationIndex(sheet) {
         key: declaration.cascadeKey,
         ruleKey,
         selectors: record.selectors,
-        scopes: record.scopes ?? [],
+        scopes: record.scopes ?? [], specificity: record.specificity,
         property: declaration.property,
         value: declaration.value,
         important: declaration.important,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-css",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "CSS semantic merge evidence and projection adapter for Frontier Lang semantic source documents.",
   "type": "module",
   "main": "./dist/index.js",