@shapeshift-labs/frontier-lang-css 0.1.12 → 0.1.13

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, 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 parallel edits whose CSS shorthand expansions overlap a longhand or sub-shorthand, preserves unchanged statement-form at-rules such as `@layer reset, components;`, 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 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, 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 and non-overlapping shorthand expansion sets; unchanged statement-form at-rules preserved in canonical output; existing scoped declaration edits when scoped cascade 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.
-- Review-only gaps: incomplete generated class-name maps, 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`, `@keyframes`, `@font-face`, `@page`, browser layout and render equivalence.
+- 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 and non-overlapping shorthand expansion sets; 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; 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 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; `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

@@ -125,6 +125,7 @@ export interface CssSemanticRecord {
   readonly conditionText?: string;
   readonly scopeKey?: string;
   readonly statementText?: string;
+  readonly blockText?: string;
   readonly scopedCascadeGraphHash?: string;
   readonly selectorTargetGraphHash?: string;
   readonly sourceSpan: CssSourceSpan;

package/dist/index.js

@@ -141,7 +141,7 @@ function sourceMapEnvelope(ast, mappings, options) {
 }
 
 function sourceRef(node, extra = {}) { return { semanticNodeId: node.id, semanticNodeKind: node.kind, semanticNodeName: node.name, ...extra }; }
-function hashableCssRecord(record) { return { kind: record.kind, selectors: record.selectors, specificity: record.specificity, scopes: record.scopes, atRuleName: record.atRuleName, conditionText: record.conditionText, statementText: record.statementText, declarations: record.declarations?.map((item) => ({ property: item.property, value: item.value, important: item.important })), proofGaps: record.proofGaps?.map((gap) => gap.code) }; }
+function hashableCssRecord(record) { return { kind: record.kind, selectors: record.selectors, specificity: record.specificity, scopes: record.scopes, atRuleName: record.atRuleName, conditionText: record.conditionText, statementText: record.statementText, blockTextHash: record.blockText ? record.rawTextHash : undefined, declarations: record.declarations?.map((item) => ({ property: item.property, value: item.value, important: item.important })), proofGaps: record.proofGaps?.map((gap) => gap.code) }; }
 function cssIdentifier(value) { return String(value ?? 'unknown').replace(/[^A-Za-z0-9_-]/g, '-').replace(/^-+/, '') || 'unknown'; }
 function cssString(value) { return String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"'); }
 function typeName(type) { return typeof type === 'string' ? type : type?.name ?? type?.kind ?? 'unknown'; }

package/dist/postcss-parser-evidence.js

@@ -100,6 +100,7 @@ function postcssAtRuleRecord(node, scopes, sourceHash, options) {
     atRuleName,
     conditionText,
     statementText: kind === 'at-rule-statement' ? rawText : undefined,
+    blockText: kind === 'at-rule' ? rawText : undefined,
     scopeKey: postcssAtRuleScopeKey(node),
     scopes,
     dependencyTokens: atRuleDependencyTokens(node, atRuleName),

package/dist/semantic-merge-at-rules.js

@@ -0,0 +1,105 @@
+function atRuleBlockEntry(record, key) {
+  if (!shouldRenderOpaqueAtRuleBlock(record)) return undefined;
+  return {
+    key,
+    scopes: record.scopes ?? [],
+    atRuleName: record.atRuleName,
+    conditionText: record.conditionText,
+    blockText: record.blockText,
+    rawTextHash: record.rawTextHash,
+    atRuleHash: record.atRuleHash
+  };
+}
+
+function shouldRenderOpaqueAtRuleBlock(record) {
+  return record.kind === 'at-rule' && !ScopeAtRules.has(record.atRuleName) && typeof record.blockText === 'string';
+}
+
+function changedAtRuleBlocks(baseIndex, currentIndex, side) {
+  const baseBlocks = baseIndex.atRuleBlocks ?? new Map();
+  const currentBlocks = currentIndex.atRuleBlocks ?? new Map();
+  const keys = unique([...baseBlocks.keys(), ...currentBlocks.keys()]);
+  return keys.flatMap((key) => {
+    const before = baseBlocks.get(key);
+    const after = currentBlocks.get(key);
+    if ((before?.rawTextHash ?? '') === (after?.rawTextHash ?? '')) return [];
+    return [{ side, key, before, after, kind: before && after ? 'update' : before ? 'delete' : 'add' }];
+  });
+}
+
+function atRuleBlockOverlapConflicts(id, sourcePath, workerChanges, headChanges, conflict) {
+  const headByKey = new Map(headChanges.map((change) => [change.key, change]));
+  return workerChanges.flatMap((workerChange) => {
+    const headChange = headByKey.get(workerChange.key);
+    if (!headChange || sameAtRuleBlockChange(workerChange, headChange)) return [];
+    return [conflict(id, sourcePath, 'css-atrule-block-conflict', 'css-atrule-block-conflict', {
+      shapeKey: workerChange.key,
+      worker: atRuleBlockChangeDetails(workerChange),
+      head: atRuleBlockChangeDetails(headChange)
+    })];
+  });
+}
+
+function applyAtRuleBlockChanges(index, changes) {
+  const atRuleBlocks = new Map(index.atRuleBlocks);
+  const atRuleBlockOrder = [...(index.atRuleBlockOrder ?? [])];
+  for (const change of changes) {
+    if (!change.after) atRuleBlocks.delete(change.key);
+    else {
+      atRuleBlocks.set(change.key, change.after);
+      if (!atRuleBlockOrder.includes(change.key)) atRuleBlockOrder.push(change.key);
+    }
+  }
+  return { ...index, atRuleBlocks, atRuleBlockOrder: atRuleBlockOrder.filter((key) => atRuleBlocks.has(key)) };
+}
+
+function renderAtRuleStatement(chunks, statement) {
+  let indent = 0;
+  for (const scope of statement.scopes ?? []) {
+    chunks.push(`${spaces(indent)}${scope} {`);
+    indent += 2;
+  }
+  chunks.push(`${spaces(indent)}${statement.statementText}`);
+  closeScopes(chunks, statement.scopes, indent);
+  chunks.push('');
+}
+
+function renderAtRuleBlock(chunks, block) {
+  if (!block) return;
+  let indent = 0;
+  for (const scope of block.scopes ?? []) {
+    chunks.push(`${spaces(indent)}${scope} {`);
+    indent += 2;
+  }
+  chunks.push(indentText(block.blockText, indent));
+  closeScopes(chunks, block.scopes, indent);
+  chunks.push('');
+}
+
+function closeScopes(chunks, scopes = [], indent) {
+  for (let index = scopes.length - 1; index >= 0; index -= 1) {
+    indent -= 2;
+    chunks.push(`${spaces(indent)}}`);
+  }
+}
+
+function atRuleBlockChangeDetails(change) {
+  const block = change.after ?? change.before;
+  return { kind: change.kind, atRuleName: block?.atRuleName, conditionText: block?.conditionText, rawTextHash: change.after?.rawTextHash };
+}
+
+function sameAtRuleBlockChange(left, right) { return (left.after?.rawTextHash ?? '') === (right.after?.rawTextHash ?? '') && left.kind === right.kind; }
+function atRuleOccurrenceKey(record, counts, prefix = 'at-rule') {
+  if (record.kind !== 'at-rule') return undefined;
+  const baseKey = `${prefix}:${[...(record.scopes ?? []), record.atRuleName, record.conditionText].join('::')}`;
+  const count = (counts.get(baseKey) ?? 0) + 1;
+  counts.set(baseKey, count);
+  return count === 1 ? baseKey : `${baseKey}#${count}`;
+}
+function unique(values) { return [...new Set(values.filter(Boolean))]; }
+function spaces(count) { return ' '.repeat(Math.max(0, count)); }
+function indentText(text, indent) { return String(text ?? '').split('\n').map((line) => line ? `${spaces(indent)}${line}` : line).join('\n'); }
+
+const ScopeAtRules = new Set(['media', 'supports', 'container', 'layer', 'scope']);
+
+export { applyAtRuleBlockChanges, atRuleBlockEntry, atRuleBlockOverlapConflicts, atRuleOccurrenceKey, changedAtRuleBlocks, renderAtRuleBlock, renderAtRuleStatement };

package/dist/semantic-merge-css-modules.js

@@ -1,3 +1,5 @@
+import { atRuleOccurrenceKey } from './semantic-merge-at-rules.js';
+
 function sheetOptions(input, side, sourcePath) {
   const prefix = side === 'base' ? 'base' : side === 'worker' ? 'worker' : 'head';
   return {
@@ -165,6 +167,7 @@ function unsupportedSourceShapeChangesForSide(baseSheet, currentSheet, declarati
 
 function sourceShapeIndex(sheet, hash) {
   const result = new Map();
+  const atRuleOccurrences = new Map();
   for (const record of sheet.records ?? []) {
     if (record.kind === 'rule') {
       const ruleKey = ruleIdentityKey(record);
@@ -180,14 +183,16 @@ function sourceShapeIndex(sheet, hash) {
       });
     }
     if (record.kind === 'at-rule') {
-      const shapeKey = `at-rule:${[...(record.scopes ?? []), record.atRuleName, record.conditionText].join('::')}`;
+      const shapeKey = atRuleOccurrenceKey(record, atRuleOccurrences);
+      const opaqueHash = isOpaqueAtRuleBlock(record) ? record.rawTextHash : undefined;
       result.set(shapeKey, {
         kind: 'at-rule',
         atRuleName: record.atRuleName,
         conditionText: record.conditionText,
+        rawTextHash: opaqueHash,
         representedByDeclarations: false,
         unsupportedReasonCode: atRuleUnsupportedReasonCode(record),
-        hash: record.atRuleHash
+        hash: opaqueHash ?? record.atRuleHash
       });
     }
     if (record.kind === 'at-rule-statement') {
@@ -213,15 +218,19 @@ function conflict(id, sourcePath, code, reasonCode, details = {}) {
 
 function sameContractChange(left, right) { return (left.after?.hash ?? '') === (right.after?.hash ?? '') && left.kind === right.kind; }
 function contractChangeDetails(change) { return { kind: change.kind, contractKind: (change.after ?? change.before)?.contractKind, name: (change.after ?? change.before)?.name, hash: change.after?.hash }; }
-function sourceShapeDetails(shape) { return shape ? { kind: shape.kind, selectors: shape.selectors, atRuleName: shape.atRuleName, conditionText: shape.conditionText, statementText: shape.statementText, representedByDeclarations: shape.representedByDeclarations } : undefined; }
+function sourceShapeDetails(shape) { return shape ? { kind: shape.kind, selectors: shape.selectors, atRuleName: shape.atRuleName, conditionText: shape.conditionText, statementText: shape.statementText, rawTextHash: shape.rawTextHash, representedByDeclarations: shape.representedByDeclarations } : undefined; }
 function sourceShapeChangeReason(before, after) {
   if (!before && after?.kind === 'at-rule') return 'css-atrule-new-scope-unsupported';
   if (before?.kind === 'at-rule' || after?.kind === 'at-rule') return after?.unsupportedReasonCode ?? before?.unsupportedReasonCode ?? 'css-atrule-condition-edit-unsupported';
   if (before?.kind === 'at-rule-statement' || after?.kind === 'at-rule-statement') return after?.unsupportedReasonCode ?? before?.unsupportedReasonCode ?? 'css-atrule-statement-unsupported';
   return 'css-source-shape-unsupported';
 }
-function atRuleUnsupportedReasonCode(record) { return record.atRuleName === 'layer' ? 'css-layer-name-edit-unsupported' : 'css-atrule-condition-edit-unsupported'; }
+function atRuleUnsupportedReasonCode(record) {
+  if (RuntimeAtRules.has(record.atRuleName)) return `css-${record.atRuleName}-runtime-equivalence-unproved`;
+  return record.atRuleName === 'layer' ? 'css-layer-name-edit-unsupported' : 'css-atrule-condition-edit-unsupported';
+}
 function atRuleStatementUnsupportedReasonCode(record) { return record.atRuleName === 'layer' ? 'css-layer-order-statement-unsupported' : 'css-atrule-statement-unsupported'; }
+function isOpaqueAtRuleBlock(record) { return record.kind === 'at-rule' && !ScopeAtRules.has(record.atRuleName) && typeof record.rawTextHash === 'string'; }
 function ruleIdentityKey(record) { return [...(record.scopes ?? []), record.selectors.join(',')].join('::'); }
 function unique(values) { return [...new Set(values.filter(Boolean))]; }
 function uniqueProofGaps(values) {
@@ -231,3 +240,6 @@ function uniqueProofGaps(values) {
 }
 
 export { cssModuleContractChanges, cssModuleContractConflicts, sheetOptions, unsupportedSourceShapeChanges, unsupportedSourceShapeConflicts };
+
+const RuntimeAtRules = new Set(['keyframes', 'font-face', 'page', 'property']);
+const ScopeAtRules = new Set(['media', 'supports', 'container', 'layer', 'scope']);

package/dist/semantic-merge.js

@@ -2,6 +2,7 @@ import { cssModuleContractChanges, cssModuleContractConflicts, sheetOptions, uns
 import { admitCascadeRuntimeProofs } from './semantic-merge-cascade-runtime.js';
 import { mergeCssDependencyGraphEvidence } from './dependency-graph.js';
 import { mergeSelectorTargetEvidence, planSelectorTargetRebase } from './semantic-merge-selector-targets.js';
+import { applyAtRuleBlockChanges, atRuleBlockEntry, atRuleBlockOverlapConflicts, atRuleOccurrenceKey, changedAtRuleBlocks, renderAtRuleBlock, renderAtRuleStatement } from './semantic-merge-at-rules.js';
 import { declarationsOverlapByCssProperty, shorthandGroupForProperty } from './semantic-merge-shorthand.js';
 
 function safeMergeCssSource(input = {}, context = {}) {
@@ -24,19 +25,24 @@ function safeMergeCssSource(input = {}, context = {}) {
     worker: changedDeclarations(indexes.base, indexes.worker, 'worker'),
     head: changedDeclarations(indexes.base, indexes.head, 'head')
   };
+  const blockChanges = {
+    worker: changedAtRuleBlocks(indexes.base, indexes.worker, 'worker'),
+    head: changedAtRuleBlocks(indexes.base, indexes.head, 'head')
+  };
   const moduleChanges = cssModuleContractChanges(sheets, hash);
   const proofConflicts = proofGapConflicts(id, sourcePath, changed, indexes);
   const parserConflicts = parserErrorConflicts(id, sourcePath, sheets);
   const overlapConflicts = [
     ...overlapDeclarationConflicts(id, sourcePath, changed.worker, changed.head),
-    ...shorthandOverlapConflicts(id, sourcePath, changed.worker, changed.head)
+    ...shorthandOverlapConflicts(id, sourcePath, changed.worker, changed.head),
+    ...atRuleBlockOverlapConflicts(id, sourcePath, blockChanges.worker, blockChanges.head, conflict)
   ];
   const moduleConflicts = cssModuleContractConflicts(id, sourcePath, moduleChanges);
   const parserEvidence = mergeParserEvidence(sheets);
   const dependencyGraphEvidence = mergeCssDependencyGraphEvidence(sheets, changed);
   const selectorTargetPlan = planSelectorTargetRebase(id, sourcePath, mergeSelectorTargetEvidence(sheets, changed), changed, input);
   const shapeChanges = unsupportedSourceShapeChanges(sheets, changed, hash);
-  const mergedIndex = applyDeclarationChanges(applyDeclarationChanges(indexes.base, selectorTargetPlan.changed.head), selectorTargetPlan.changed.worker);
+  const mergedIndex = applyAtRuleBlockChanges(applyAtRuleBlockChanges(applyDeclarationChanges(applyDeclarationChanges(indexes.base, selectorTargetPlan.changed.head), selectorTargetPlan.changed.worker), blockChanges.head), blockChanges.worker);
   const mergedSourceText = renderDeclarationIndex(mergedIndex);
   const cascadeRuntimeAdmission = admitCascadeRuntimeProofs({
     id,
@@ -68,7 +74,15 @@ function declarationIndex(sheet) {
   const declarations = new Map();
   const order = [];
   const statements = [];
+  const atRuleBlocks = new Map();
+  const atRuleBlockOrder = [];
+  const atRuleOccurrences = new Map();
   for (const record of sheet.records) {
+    const block = atRuleBlockEntry(record, atRuleOccurrenceKey(record, atRuleOccurrences));
+    if (block) {
+      atRuleBlocks.set(block.key, block);
+      atRuleBlockOrder.push(block.key);
+    }
     if (record.kind === 'at-rule-statement') {
       statements.push({
         key: record.atRuleHash,
@@ -97,7 +111,7 @@ function declarationIndex(sheet) {
       order.push(entry.key);
     }
   }
-  return { declarations, order: unique(order), statements };
+  return { declarations, order: unique(order), statements, atRuleBlocks, atRuleBlockOrder: unique(atRuleBlockOrder) };
 }
 
 function changedDeclarations(baseIndex, currentIndex, side) {
@@ -210,7 +224,7 @@ function applyDeclarationChanges(index, changes) {
       if (!order.includes(change.key)) order.push(change.key);
     }
   }
-  return { declarations, order: order.filter((key) => declarations.has(key)), statements: index.statements ?? [] };
+  return { ...index, declarations, order: order.filter((key) => declarations.has(key)), statements: index.statements ?? [] };
 }
 
 function renderDeclarationIndex(index) {
@@ -222,26 +236,13 @@ function renderDeclarationIndex(index) {
   }
   const chunks = [];
   for (const statement of index.statements ?? []) renderAtRuleStatement(chunks, statement);
+  for (const key of index.atRuleBlockOrder ?? []) renderAtRuleBlock(chunks, index.atRuleBlocks.get(key));
   for (const declarations of groups.values()) {
     renderDeclarationGroup(chunks, declarations);
   }
   return `${chunks.join('\n').trimEnd()}\n`;
 }
 
-function renderAtRuleStatement(chunks, statement) {
-  let indent = 0;
-  for (const scope of statement.scopes ?? []) {
-    chunks.push(`${spaces(indent)}${scope} {`);
-    indent += 2;
-  }
-  chunks.push(`${spaces(indent)}${statement.statementText}`);
-  for (let index = (statement.scopes ?? []).length - 1; index >= 0; index -= 1) {
-    indent -= 2;
-    chunks.push(`${spaces(indent)}}`);
-  }
-  chunks.push('');
-}
-
 function renderDeclarationGroup(chunks, declarations) {
   const first = declarations[0];
   let indent = 0;

package/package.json

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