fix(core): boundary-guard @-reference parsing for mid-token literals (#323)

AT_VARIABLE_REGEX matched @ anywhere in a string, so a retina URL like
url("image@2x.png") parsed @2x.png as a variable reference — silently
emitting a dead var(--2x--png) before SF-13, and throwing after SF-13
tightened ref validation. Require a non-word boundary before @ so it only
starts a reference when not preceded by a word character.

Implements SF-33.

Author: alexgrozav

.changeset/core-at-ref-word-boundary.md

@@ -0,0 +1,6 @@
+---
+"@styleframe/core": patch
+"styleframe": patch
+---
+
+Boundary-guard `@`-reference parsing so a `@` mid-token is a literal, not a reference. `AT_VARIABLE_REGEX` matched `@` anywhere in a string, so a retina URL like `url("image@2x.png")` parsed `@2x.png` as a variable reference — silently emitting a dead `var(--2x--png)` before SF-13, and *throwing* `Variable "2x.png" is not defined` after SF-13 tightened ref validation. The regex now requires a non-word boundary before `@` (`(?<!\w)`), so `@` only starts a reference when not preceded by a word character. Genuine leading-`@` refs (`@color.primary`, `1px solid @spacing.sm`, `@border.width solid @color.primary`) are unchanged, byte for byte; only `@`-mid-token literals change — from broken/throwing to passthrough.

engine/core/src/tokens/atRule.test.ts

@@ -668,13 +668,16 @@ describe("createMediaFunction", () => {
 			const result = media(
 				"(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)",
 				{
-					backgroundImage: 'url("image-2x.png")',
+					backgroundImage: 'url("image@2x.png")',
 				},
 			);
 
 			expect(result.rule).toBe(
 				"(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)",
 			);
+			// A retina URL's mid-token @ must stay a literal string, not parse as
+			// a reference (no throw, no dead var(--2x--png)). See SF-33.
+			expect(result.declarations.backgroundImage).toBe('url("image@2x.png")');
 		});
 
 		it("should handle empty query string", () => {

engine/core/src/tokens/resolve.test.ts

@@ -63,6 +63,27 @@ describe("parseAtReferences", () => {
 
 		expect(result).toEqual([]);
 	});
+
+	it("should not treat a mid-token @ as a reference (retina URL)", () => {
+		const result = parseAtReferences('url("image@2x.png")');
+
+		expect(result).toEqual(['url("image@2x.png")']);
+	});
+
+	it("should not treat a @ preceded by a word character as a reference", () => {
+		const result = parseAtReferences("foo@bar");
+
+		expect(result).toEqual(["foo@bar"]);
+	});
+
+	it("should still parse a leading @ reference after a non-word boundary", () => {
+		const result = parseAtReferences('url("image@2x.png") @color.primary');
+
+		expect(result).toEqual([
+			'url("image@2x.png") ',
+			{ type: "reference", name: "color.primary", fallback: undefined },
+		]);
+	});
 });
 
 describe("findVariableInScope", () => {
@@ -284,6 +305,16 @@ describe("createPropertyValueResolver", () => {
 		it("should return empty strings unchanged", () => {
 			expect(resolvePropertyValue("")).toBe("");
 		});
+
+		it("should return a retina URL literal unchanged (no throw, no ref)", () => {
+			expect(resolvePropertyValue('url("image@2x.png")')).toBe(
+				'url("image@2x.png")',
+			);
+		});
+
+		it("should return a bare mid-token @ literal unchanged", () => {
+			expect(resolvePropertyValue("foo@bar")).toBe("foo@bar");
+		});
 	});
 
 	describe("exact @ reference", () => {

engine/core/src/tokens/resolve.ts

@@ -23,7 +23,10 @@ export function trackReferenceUsage(root: Root, value: TokenValue): void {
 
 export type RefFunction = (variable: string, fallback?: string) => Reference;
 
-const AT_VARIABLE_REGEX = /@([\w.-]+)/g;
+// `@` only starts a reference at a non-word boundary. Guarding with `(?<!\w)`
+// keeps mid-token literals like a retina URL `url("image@2x.png")` intact
+// instead of parsing `@2x.png` as a variable reference (SF-33).
+const AT_VARIABLE_REGEX = /(?<!\w)@([\w.-]+)/g;
 
 export function parseAtReferences(str: string): TokenValue[] {
 	const parts: TokenValue[] = [];