@ccheever/exact-renderer 0.1.0

package/src/classname-resolve.ts

@@ -0,0 +1,553 @@
+import type { CanonicalStyle } from './types.js';
+import type {
+  ClassNameResolutionContext,
+  InteractionState,
+  MediaCondition,
+  MediaState,
+  SerializedCompiledFragment,
+  SerializedExactStyleSheet,
+  SerializedFragmentCondition,
+  SiblingPosition,
+  SupportedPseudo,
+} from './classname-contract.js';
+
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+/** Layer 1 cache limit from RFC 0024. */
+const CLASS_CACHE_LIMIT = 1024;
+
+interface CompiledFragment {
+  readonly order: number;
+  readonly condition: SerializedFragmentCondition | null;
+  readonly mediaGate: readonly MediaCondition[] | null;
+  readonly style: CanonicalStyle;
+}
+
+interface RegisteredExactStyleSheet {
+  readonly sourceId: string;
+  readonly sheetOrder: number;
+  readonly classes: Map<string, CompiledFragment[]>;
+  readonly warnings: string[];
+}
+
+interface CachedClassResolution {
+  readonly base: CanonicalStyle;
+  readonly conditionals: CompiledFragment[];
+  readonly hasConditionals: boolean;
+}
+
+const __initW =
+  typeof globalThis.innerWidth === 'number' ? globalThis.innerWidth : 390;
+const __initH =
+  typeof globalThis.innerHeight === 'number' ? globalThis.innerHeight : 844;
+
+let currentMediaState: MediaState = {
+  width: __initW,
+  height: __initH,
+  orientation: __initH > __initW ? 'portrait' : 'landscape',
+  colorScheme: 'light',
+  reducedMotion: false,
+};
+
+const mediaStateListeners = new Set<() => void>();
+const stylesheetRegistry = new Map<string, RegisteredExactStyleSheet>();
+const emittedCompilerWarnings = new Set<string>();
+const emittedUnknownClassWarnings = new Set<string>();
+const classResolutionCache = new Map<string, CachedClassResolution>();
+let nextSheetOrder = 0;
+
+type RuntimeClassNameResolver = (
+  className: unknown,
+  context?: ClassNameResolutionContext,
+) => CanonicalStyle;
+
+declare global {
+  var __exactClassNameResolver: RuntimeClassNameResolver | undefined;
+  var __exactHasExactStylesheets: boolean | undefined;
+}
+
+export type {
+  ClassNameResolutionContext,
+  InteractionState,
+  MediaState,
+  MediaCondition,
+  SiblingPosition,
+} from './classname-contract.js';
+
+export function getMediaState(): MediaState {
+  return currentMediaState;
+}
+
+export function setMediaState(state: Partial<MediaState>): void {
+  const next: MediaState = { ...currentMediaState, ...state };
+  if (
+    next.width === currentMediaState.width &&
+    next.height === currentMediaState.height &&
+    next.orientation === currentMediaState.orientation &&
+    next.colorScheme === currentMediaState.colorScheme &&
+    next.reducedMotion === currentMediaState.reducedMotion
+  ) {
+    return;
+  }
+
+  currentMediaState = next;
+  classResolutionCache.clear();
+
+  for (const listener of mediaStateListeners) {
+    try {
+      listener();
+    } catch (error) {
+      if (__DEV__) {
+        console.warn('Media state listener error:', error);
+      }
+    }
+  }
+}
+
+export function subscribeMediaState(listener: () => void): () => void {
+  mediaStateListeners.add(listener);
+  return () => {
+    mediaStateListeners.delete(listener);
+  };
+}
+
+if (typeof globalThis.addEventListener === 'function') {
+  globalThis.addEventListener('resize', () => {
+    const width = globalThis.innerWidth ?? currentMediaState.width;
+    const height = globalThis.innerHeight ?? currentMediaState.height;
+    setMediaState({
+      width,
+      height,
+      orientation: height > width ? 'portrait' : 'landscape',
+    });
+  });
+}
+
+/**
+ * Register a precompiled stylesheet artifact.
+ *
+ * The runtime intentionally accepts only serialized data here. Parsing raw CSS
+ * text would pull the compiler back into the client bundle and reintroduce the
+ * exact environment leak this RFC removes.
+ */
+export function __registerExactStylesheet(
+  sourceId: string,
+  artifact: SerializedExactStyleSheet,
+): void {
+  const previous = stylesheetRegistry.get(sourceId);
+  const compiled = deserializeExactStylesheet(
+    sourceId,
+    artifact,
+    previous?.sheetOrder,
+  );
+
+  stylesheetRegistry.set(sourceId, compiled);
+  classResolutionCache.clear();
+  publishClassNameRuntimeState();
+
+  if (__DEV__) {
+    for (const warning of compiled.warnings) {
+      if (emittedCompilerWarnings.has(warning)) {
+        continue;
+      }
+      emittedCompilerWarnings.add(warning);
+      console.warn(warning);
+    }
+  }
+}
+
+export function __clearExactStylesheets(): void {
+  stylesheetRegistry.clear();
+  classResolutionCache.clear();
+  emittedCompilerWarnings.clear();
+  emittedUnknownClassWarnings.clear();
+  nextSheetOrder = 0;
+  publishClassNameRuntimeState();
+}
+
+export function resolveClassNameStyle(
+  className: unknown,
+  context?: ClassNameResolutionContext,
+): CanonicalStyle {
+  const normalizedClassName = normalizeClassNameValue(className);
+  if (normalizedClassName.length === 0 || stylesheetRegistry.size === 0) {
+    return {};
+  }
+
+  const cached = getOrComputeCachedResolution(normalizedClassName);
+
+  if (!cached.hasConditionals) {
+    return cached.base;
+  }
+
+  let resolved: CanonicalStyle | undefined;
+  for (const fragment of cached.conditionals) {
+    if (fragment.mediaGate && !fragment.mediaGate.every(evaluateMediaCondition)) {
+      continue;
+    }
+
+    if (evaluateCondition(fragment.condition!, context)) {
+      if (!resolved) {
+        resolved = { ...cached.base };
+      }
+      Object.assign(resolved, fragment.style);
+    }
+  }
+
+  return resolved ?? cached.base;
+}
+
+export function classNameHasInteractiveConditions(className: unknown): boolean {
+  const normalizedClassName = normalizeClassNameValue(className);
+  if (normalizedClassName.length === 0 || stylesheetRegistry.size === 0) {
+    return false;
+  }
+
+  const cached = getOrComputeCachedResolution(normalizedClassName);
+  return cached.conditionals.some((fragment) => {
+    if (!fragment.condition) {
+      return false;
+    }
+
+    if (fragment.condition.type === 'pseudo') {
+      return (
+        fragment.condition.pseudo === 'hover' ||
+        fragment.condition.pseudo === 'focus' ||
+        fragment.condition.pseudo === 'active' ||
+        fragment.condition.pseudo === 'focus-visible'
+      );
+    }
+
+    return false;
+  });
+}
+
+export function classNameHasMediaConditions(className: unknown): boolean {
+  const normalizedClassName = normalizeClassNameValue(className);
+  if (normalizedClassName.length === 0 || stylesheetRegistry.size === 0) {
+    return false;
+  }
+
+  const cached = getOrComputeCachedResolution(normalizedClassName);
+  return cached.conditionals.some(
+    (fragment) =>
+      fragment.condition?.type === 'media' ||
+      Boolean(fragment.mediaGate && fragment.mediaGate.length > 0),
+  );
+}
+
+function publishClassNameRuntimeState(): void {
+  globalThis.__exactClassNameResolver = resolveClassNameStyle;
+  globalThis.__exactHasExactStylesheets = stylesheetRegistry.size > 0;
+}
+
+function deserializeExactStylesheet(
+  sourceId: string,
+  artifact: SerializedExactStyleSheet,
+  preserveSheetOrder?: number,
+): RegisteredExactStyleSheet {
+  const classes = new Map<string, CompiledFragment[]>();
+
+  for (const [className, fragments] of Object.entries(artifact.classes)) {
+    classes.set(
+      className,
+      fragments.map((fragment) => deserializeFragment(fragment)),
+    );
+  }
+
+  return {
+    sourceId,
+    sheetOrder: preserveSheetOrder ?? nextSheetOrder++,
+    classes,
+    warnings: [...artifact.warnings],
+  };
+}
+
+function deserializeFragment(fragment: SerializedCompiledFragment): CompiledFragment {
+  return {
+    order: fragment.order,
+    condition: fragment.condition ? cloneCondition(fragment.condition) : null,
+    mediaGate: cloneMediaConditions(fragment.mediaGate),
+    style: { ...fragment.style },
+  };
+}
+
+function cloneCondition(
+  condition: SerializedFragmentCondition,
+): SerializedFragmentCondition {
+  switch (condition.type) {
+    case 'pseudo':
+      return {
+        type: 'pseudo',
+        pseudo: condition.pseudo,
+      };
+    case 'media':
+      return {
+        type: 'media',
+        media: cloneMediaConditions(condition.media) ?? [],
+      };
+    case 'group':
+      return {
+        type: 'group',
+        groupName: condition.groupName,
+        pseudo: condition.pseudo,
+      };
+    case 'peer':
+      return {
+        type: 'peer',
+        peerName: condition.peerName,
+        pseudo: condition.pseudo,
+      };
+  }
+}
+
+function cloneMediaConditions(
+  conditions: readonly MediaCondition[] | null | undefined,
+): readonly MediaCondition[] | null {
+  if (!conditions || conditions.length === 0) {
+    return null;
+  }
+
+  return conditions.map((condition) => ({
+    feature: condition.feature,
+    value: condition.value,
+  }));
+}
+
+function getOrComputeCachedResolution(className: string): CachedClassResolution {
+  const existing = classResolutionCache.get(className);
+  if (existing) {
+    touchCacheEntry(className, existing);
+    return existing;
+  }
+
+  const tokens = className.split(/\s+/).filter(Boolean);
+  const orderedSheets = [...stylesheetRegistry.values()].sort(
+    (left, right) => left.sheetOrder - right.sheetOrder,
+  );
+
+  const baseFragments: Array<{
+    sheetOrder: number;
+    fragment: CompiledFragment;
+  }> = [];
+  const conditionalFragments: Array<{
+    sheetOrder: number;
+    fragment: CompiledFragment;
+  }> = [];
+
+  for (const sheet of orderedSheets) {
+    for (const token of tokens) {
+      const fragments = sheet.classes.get(token);
+      if (!fragments || fragments.length === 0) {
+        continue;
+      }
+
+      for (const fragment of fragments) {
+        // `mediaGate` is part of the conditional evaluation contract even when
+        // a fragment has no additional pseudo/group/peer discriminator.
+        // Treating those fragments as unconditional would permanently apply the
+        // gated style and make media-only overlays impossible to model.
+        if (fragment.condition === null && fragment.mediaGate === null) {
+          baseFragments.push({ sheetOrder: sheet.sheetOrder, fragment });
+        } else {
+          conditionalFragments.push({ sheetOrder: sheet.sheetOrder, fragment });
+        }
+      }
+    }
+  }
+
+  if (__DEV__) {
+    warnAboutUnknownClasses(tokens);
+  }
+
+  baseFragments.sort(compareFragmentOrder);
+  conditionalFragments.sort(compareFragmentOrder);
+
+  let base: CanonicalStyle = {};
+  for (const entry of baseFragments) {
+    base = { ...base, ...entry.fragment.style };
+  }
+
+  const cached: CachedClassResolution = {
+    base,
+    conditionals: conditionalFragments.map((entry) => entry.fragment),
+    hasConditionals: conditionalFragments.length > 0,
+  };
+
+  touchCacheEntry(className, cached);
+  return cached;
+}
+
+function touchCacheEntry(
+  className: string,
+  cached: CachedClassResolution,
+): void {
+  classResolutionCache.delete(className);
+  classResolutionCache.set(className, cached);
+
+  if (classResolutionCache.size <= CLASS_CACHE_LIMIT) {
+    return;
+  }
+
+  const oldestKey = classResolutionCache.keys().next().value;
+  if (typeof oldestKey === 'string') {
+    classResolutionCache.delete(oldestKey);
+  }
+}
+
+function warnAboutUnknownClasses(tokens: string[]): void {
+  for (const token of tokens) {
+    if (token.length === 0) {
+      continue;
+    }
+
+    const known = [...stylesheetRegistry.values()].some((sheet) =>
+      sheet.classes.has(token),
+    );
+    if (known) {
+      continue;
+    }
+
+    const warning = `⚠ exact-css: Unknown class "${token}" in className. No matching native CSS rule was registered.`;
+    if (emittedUnknownClassWarnings.has(warning)) {
+      continue;
+    }
+
+    emittedUnknownClassWarnings.add(warning);
+    console.warn(warning);
+  }
+}
+
+function evaluateCondition(
+  condition: SerializedFragmentCondition,
+  context: ClassNameResolutionContext | undefined,
+): boolean {
+  switch (condition.type) {
+    case 'pseudo':
+      return evaluatePseudoCondition(condition.pseudo, context);
+    case 'media':
+      return condition.media.every(evaluateMediaCondition);
+    case 'group': {
+      const groupState = context?.groupStates?.get(condition.groupName);
+      if (!groupState) {
+        return false;
+      }
+      return getPseudoFromInteraction(condition.pseudo, groupState);
+    }
+    case 'peer': {
+      const peerState = context?.peerStates?.getState(condition.peerName);
+      if (!peerState) {
+        return false;
+      }
+      return getPseudoFromInteraction(condition.pseudo, peerState);
+    }
+  }
+}
+
+function evaluatePseudoCondition(
+  pseudo: SupportedPseudo,
+  context: ClassNameResolutionContext | undefined,
+): boolean {
+  switch (pseudo) {
+    case 'disabled':
+      return isDisabledPseudoActive(context?.props);
+    case 'hover':
+      return context?.interaction?.hovered === true;
+    case 'focus':
+      return context?.interaction?.focused === true;
+    case 'active':
+      return context?.interaction?.active === true;
+    case 'focus-visible':
+      return context?.interaction?.focusVisible === true;
+    case 'first-child':
+      return context?.position?.isFirst === true;
+    case 'last-child':
+      return context?.position?.isLast === true;
+  }
+}
+
+function evaluateMediaCondition(condition: MediaCondition): boolean {
+  const state = currentMediaState;
+  switch (condition.feature) {
+    case 'min-width':
+      return typeof condition.value === 'number' && state.width >= condition.value;
+    case 'max-width':
+      return typeof condition.value === 'number' && state.width <= condition.value;
+    case 'gt-width':
+      return typeof condition.value === 'number' && state.width > condition.value;
+    case 'lt-width':
+      return typeof condition.value === 'number' && state.width < condition.value;
+    case 'min-height':
+      return typeof condition.value === 'number' && state.height >= condition.value;
+    case 'max-height':
+      return typeof condition.value === 'number' && state.height <= condition.value;
+    case 'gt-height':
+      return typeof condition.value === 'number' && state.height > condition.value;
+    case 'lt-height':
+      return typeof condition.value === 'number' && state.height < condition.value;
+    case 'orientation':
+      return state.orientation === condition.value;
+    case 'prefers-color-scheme':
+      return state.colorScheme === condition.value;
+    case 'prefers-reduced-motion':
+      if (condition.value === 'reduce') {
+        return state.reducedMotion;
+      }
+      if (condition.value === 'no-preference') {
+        return !state.reducedMotion;
+      }
+      return false;
+  }
+}
+
+function getPseudoFromInteraction(
+  pseudo: 'hover' | 'focus' | 'active',
+  state: InteractionState,
+): boolean {
+  switch (pseudo) {
+    case 'hover':
+      return state.hovered;
+    case 'focus':
+      return state.focused;
+    case 'active':
+      return state.active;
+  }
+}
+
+function compareFragmentOrder(
+  left: { sheetOrder: number; fragment: CompiledFragment },
+  right: { sheetOrder: number; fragment: CompiledFragment },
+): number {
+  if (left.sheetOrder !== right.sheetOrder) {
+    return left.sheetOrder - right.sheetOrder;
+  }
+  return left.fragment.order - right.fragment.order;
+}
+
+function normalizeClassNameValue(value: unknown): string {
+  if (typeof value !== 'string') {
+    return '';
+  }
+
+  return value
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .join(' ');
+}
+
+function isDisabledPseudoActive(
+  props: Record<string, unknown> | undefined,
+): boolean {
+  if (!props) {
+    return false;
+  }
+
+  return (
+    props.disabled === true ||
+    props.accessibilityDisabled === true ||
+    props['aria-disabled'] === true
+  );
+}
+
+publishClassNameRuntimeState();

package/src/classname-runtime.ts

@@ -0,0 +1,29 @@
+import type { CanonicalStyle } from './types.js';
+import type { ClassNameResolutionContext } from './classname-contract.js';
+
+type RuntimeClassNameResolver = (
+  className: unknown,
+  context?: ClassNameResolutionContext,
+) => CanonicalStyle;
+
+declare global {
+  var __exactClassNameResolver: RuntimeClassNameResolver | undefined;
+  var __exactHasExactStylesheets: boolean | undefined;
+}
+
+export type { ClassNameResolutionContext } from './classname-contract.js';
+
+export function resolveClassNameStyle(
+  className: unknown,
+  context?: ClassNameResolutionContext,
+): CanonicalStyle {
+  if (
+    typeof className !== 'string' ||
+    className.trim().length === 0 ||
+    globalThis.__exactHasExactStylesheets !== true
+  ) {
+    return {};
+  }
+
+  return globalThis.__exactClassNameResolver?.(className, context) ?? {};
+}