@shapeshift-labs/frontier-lang-css 0.1.3 → 0.1.4

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, cascade keys, CSS Modules exports, ICSS edges, source spans, stable hashes, and fail-closed proof gaps for cascade/render-sensitive CSS surfaces. `safeMergeCssSource` admits independent unscoped declaration edits by cascade key, and for `.module.css` files it classifies exported local classes, `composes`, and ICSS import/export records as explicit merge contracts.
+`sourceMap.mappings` links emitted rule blocks back to Frontier Lang semantic node ids. `createCssSemanticMergeEvidence` records selectors, specificity, declarations, custom properties, cascade keys, 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, and for `.module.css` files it classifies exported local classes, `composes`, and ICSS import/export records as explicit merge contracts.
 
 ## Support Boundary
 
-- Ready evidence: style rules, selectors, specificity, declarations, custom properties, CSS Modules local exports, generated class-name map coverage, JS/TS use-site graph hashes, composition graph hashes, ICSS graph hashes, source spans, stable hashes.
-- Safe merge: independent unscoped declarations with non-overlapping cascade keys; 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, shorthands without longhand expansion, scoped cascade under `@media` / `@supports` / `@container` / `@layer`, `@keyframes`, `@font-face`, `@page`, browser layout and render equivalence.
+- Ready evidence: style rules, selectors, specificity, declarations, custom properties, 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 spans, stable hashes.
+- Safe merge: independent declarations with non-overlapping cascade keys; existing scoped declaration edits when scoped cascade graph 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, shorthands without longhand expansion, unproved or structurally changed scoped cascade under `@media` / `@supports` / `@container` / `@layer`, `@keyframes`, `@font-face`, `@page`, browser layout and render equivalence.
 - Claims: `autoMergeClaim`, `semanticEquivalenceClaim`, `browserCascadeEquivalenceClaim`, and `browserRenderEquivalenceClaim` remain false.

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export interface CssProjectionOptions {
   readonly jsTsUseSiteGraphHash?: string;
   readonly cssModuleCompositionGraphHash?: string;
   readonly icssGraphHash?: string;
+  readonly scopedCascadeGraphHash?: string;
   readonly targetPath?: string;
   readonly semanticIndexId?: string;
   readonly sourceSpansBySemanticNodeId?: Readonly<Record<string, CssSourceSpan>>;
@@ -124,6 +125,7 @@ export interface CssSemanticRecord {
   readonly atRuleName?: string;
   readonly conditionText?: string;
   readonly scopeKey?: string;
+  readonly scopedCascadeGraphHash?: string;
   readonly sourceSpan: CssSourceSpan;
   readonly sourceHash: string;
   readonly ruleHash?: string;
@@ -266,6 +268,7 @@ export interface CssSafeMergeInput {
   readonly jsTsUseSiteGraphHash?: string;
   readonly cssModuleCompositionGraphHash?: string;
   readonly icssGraphHash?: string;
+  readonly scopedCascadeGraphHash?: string;
   readonly baseGeneratedClassNameMap?: Readonly<Record<string, string>>;
   readonly workerGeneratedClassNameMap?: Readonly<Record<string, string>>;
   readonly headGeneratedClassNameMap?: Readonly<Record<string, string>>;
@@ -281,6 +284,9 @@ export interface CssSafeMergeInput {
   readonly baseIcssGraphHash?: string;
   readonly workerIcssGraphHash?: string;
   readonly headIcssGraphHash?: string;
+  readonly baseScopedCascadeGraphHash?: string;
+  readonly workerScopedCascadeGraphHash?: string;
+  readonly headScopedCascadeGraphHash?: string;
 }
 
 export declare function toCssAst(document: FrontierLangDocument, options?: CssProjectionOptions): CssAstStylesheet;

package/dist/index.js

@@ -59,7 +59,7 @@ export function emitCssWithSourceMap(document, options = {}) {
 export function parseCssSemanticSheet(sourceText, options = {}) {
   const lineStarts = computeLineStarts(sourceText);
   const sourceHash = options.sourceHash ?? hashSemanticValue({ kind: 'frontier.lang.css.source.v1', sourceText });
-  const records = parseCssBlocks(sourceText, 0, sourceText.length, [], lineStarts, sourceHash);
+  const records = parseCssBlocks(sourceText, 0, sourceText.length, [], lineStarts, sourceHash, options);
   const cssModules = createCssModuleEvidence(records, options, sourceHash);
   const proofGaps = [
     ...records.flatMap((record) => record.proofGaps ?? []),
@@ -112,7 +112,7 @@ export function safeMergeCssSource(input = {}) {
   return safeMergeCssSourceImpl(input, { parseCssSemanticSheet, hashSemanticValue });
 }
 
-function parseCssBlocks(sourceText, start, end, scopes, lineStarts, sourceHash) {
+function parseCssBlocks(sourceText, start, end, scopes, lineStarts, sourceHash, options) {
   const records = [];
   let index = start;
   while (index < end) {
@@ -124,23 +124,23 @@ function parseCssBlocks(sourceText, start, end, scopes, lineStarts, sourceHash)
     const prelude = sourceText.slice(preludeStart, open).replace(/\/\*[\s\S]*?\*\//g, '').trim();
     const body = sourceText.slice(open + 1, close);
     if (prelude.startsWith('@')) {
-      const at = parseAtRule(prelude, preludeStart, close + 1, lineStarts, sourceHash, scopes);
+      const at = parseAtRule(prelude, preludeStart, close + 1, lineStarts, sourceHash, scopes, options);
       records.push(at);
-      if (ScopeAtRules.has(at.atRuleName)) records.push(...parseCssBlocks(sourceText, open + 1, close, [...scopes, at.scopeKey], lineStarts, sourceHash));
+      if (ScopeAtRules.has(at.atRuleName)) records.push(...parseCssBlocks(sourceText, open + 1, close, [...scopes, at.scopeKey], lineStarts, sourceHash, options));
     } else if (prelude) {
-      records.push(cssRuleRecord(prelude, body, preludeStart, close + 1, lineStarts, sourceHash, scopes));
+      records.push(cssRuleRecord(prelude, body, preludeStart, close + 1, lineStarts, sourceHash, scopes, options));
     }
     index = close + 1;
   }
   return records;
 }
 
-function cssRuleRecord(prelude, body, start, end, lineStarts, sourceHash, scopes) {
+function cssRuleRecord(prelude, body, start, end, lineStarts, sourceHash, scopes, options) {
   const selectors = prelude.split(',').map((selector) => selector.trim()).filter(Boolean);
   const declarations = parseDeclarations(body);
   const proofGaps = [
     ...declarations.filter((declaration) => ShorthandProperties.has(declaration.property)).map((declaration) => proofGap('css-shorthand-expansion-unproved', `CSS shorthand ${declaration.property} needs longhand expansion evidence.`)),
-    ...scopes.length ? [proofGap('css-scoped-cascade-equivalence-unproved', 'Scoped cascade equivalence requires browser/style evidence.')] : []
+    ...scopes.length && !options.scopedCascadeGraphHash ? [proofGap('css-scoped-cascade-equivalence-unproved', 'Scoped cascade equivalence requires browser/style evidence.')] : []
   ];
   return compactRecord({
     kind: 'rule',
@@ -155,6 +155,7 @@ function cssRuleRecord(prelude, body, start, end, lineStarts, sourceHash, scopes
       declarationHash: hashSemanticValue({ kind: 'frontier.lang.css.declaration.v1', scopes, selectors, declaration })
     })),
     customProperties: declarations.filter((declaration) => declaration.property.startsWith('--')).map((declaration) => declaration.property),
+    scopedCascadeGraphHash: scopes.length ? options.scopedCascadeGraphHash : undefined,
     sourceSpan: sourceSpan(start, end, lineStarts),
     sourceHash,
     ruleHash: hashSemanticValue({ kind: 'frontier.lang.css.rule.v1', selectors, scopes, declarations }),
@@ -162,19 +163,20 @@ function cssRuleRecord(prelude, body, start, end, lineStarts, sourceHash, scopes
   });
 }
 
-function parseAtRule(prelude, start, end, lineStarts, sourceHash, scopes) {
+function parseAtRule(prelude, start, end, lineStarts, sourceHash, scopes, options) {
   const match = /^@([A-Za-z-]+)\s*([\s\S]*)$/.exec(prelude);
   const atRuleName = match?.[1]?.toLowerCase() ?? 'unknown';
   const conditionText = match?.[2]?.trim() ?? '';
   const proofGaps = [];
   if (RuntimeAtRules.has(atRuleName)) proofGaps.push(proofGap(`css-${atRuleName}-runtime-equivalence-unproved`, `CSS @${atRuleName} semantics require browser evidence.`));
-  if (ScopeAtRules.has(atRuleName)) proofGaps.push(proofGap(`css-${atRuleName}-cascade-scope-unproved`, `CSS @${atRuleName} scoped cascade requires condition evaluation evidence.`));
+  if (ScopeAtRules.has(atRuleName) && !options.scopedCascadeGraphHash) proofGaps.push(proofGap(`css-${atRuleName}-cascade-scope-unproved`, `CSS @${atRuleName} scoped cascade requires condition evaluation evidence.`));
   return compactRecord({
     kind: 'at-rule',
     atRuleName,
     conditionText,
     scopeKey: `@${atRuleName} ${conditionText}`.trim(),
     scopes,
+    scopedCascadeGraphHash: ScopeAtRules.has(atRuleName) ? options.scopedCascadeGraphHash : undefined,
     sourceSpan: sourceSpan(start, end, lineStarts),
     sourceHash,
     atRuleHash: hashSemanticValue({ kind: 'frontier.lang.css.atRule.v1', atRuleName, conditionText, scopes }),

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

@@ -8,7 +8,8 @@ function sheetOptions(input, side, sourcePath) {
     generatedClassNameMapHash: input[`${prefix}GeneratedClassNameMapHash`] ?? input.generatedClassNameMapHash,
     jsTsUseSiteGraphHash: input[`${prefix}JsTsUseSiteGraphHash`] ?? input.jsTsUseSiteGraphHash,
     cssModuleCompositionGraphHash: input[`${prefix}CssModuleCompositionGraphHash`] ?? input.cssModuleCompositionGraphHash,
-    icssGraphHash: input[`${prefix}IcssGraphHash`] ?? input.icssGraphHash
+    icssGraphHash: input[`${prefix}IcssGraphHash`] ?? input.icssGraphHash,
+    scopedCascadeGraphHash: input[`${prefix}ScopedCascadeGraphHash`] ?? input.scopedCascadeGraphHash
   };
 }
 

package/dist/semantic-merge.js

@@ -150,18 +150,33 @@ function renderDeclarationIndex(index) {
   const groups = new Map();
   for (const key of index.order) {
     const declaration = index.declarations.get(key);
-    if (!declaration || declaration.scopes.length) continue;
+    if (!declaration) continue;
     groups.set(declaration.ruleKey, [...(groups.get(declaration.ruleKey) ?? []), declaration]);
   }
   const chunks = [];
   for (const declarations of groups.values()) {
-    chunks.push(`${declarations[0].selectors.join(', ')} {`);
-    for (const declaration of declarations) chunks.push(`  ${declaration.property}: ${declaration.value};`);
-    chunks.push('}', '');
+    renderDeclarationGroup(chunks, declarations);
   }
   return `${chunks.join('\n').trimEnd()}\n`;
 }
 
+function renderDeclarationGroup(chunks, declarations) {
+  const first = declarations[0];
+  let indent = 0;
+  for (const scope of first.scopes) {
+    chunks.push(`${spaces(indent)}${scope} {`);
+    indent += 2;
+  }
+  chunks.push(`${spaces(indent)}${first.selectors.join(', ')} {`);
+  for (const declaration of declarations) chunks.push(`${spaces(indent + 2)}${declaration.property}: ${declaration.value};`);
+  chunks.push(`${spaces(indent)}}`);
+  for (let index = first.scopes.length - 1; index >= 0; index -= 1) {
+    indent -= 2;
+    chunks.push(`${spaces(indent)}}`);
+  }
+  chunks.push('');
+}
+
 function merged(id, sourcePath, sourceText, operation, hash, extra = {}) {
   return result(id, sourcePath, 'merged', {
     operation,
@@ -209,6 +224,7 @@ function proofGapsForDeclaration(record, declaration) {
   return (record.proofGaps ?? []).filter((gap) => gap.code !== 'css-shorthand-expansion-unproved' || gap.summary.includes(` ${declaration.property} `));
 }
 function unique(values) { return [...new Set(values.filter(Boolean))]; }
+function spaces(count) { return ' '.repeat(Math.max(0, count)); }
 
 function shorthandGroupForProperty(property) {
   if (ShorthandGroups.has(property)) return property;

package/package.json

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