tjs-lang 0.8.6 → 0.9.0

package/src/css/perf.bench.test.ts

@@ -0,0 +1,109 @@
+/**
+ * `tjs-lang/css` phase 5 — the "safe is fast" data point.
+ *
+ * Validates a theme-sized style object (à la a real design-system theme: a
+ * `:root` variable block plus dozens of component rules with hover/focus states
+ * and a media query) with the COMPLETE predicate set, and times it. Confirms the
+ * PoC ballpark (~0.1ms/theme) now that colors + dimensions + shorthands +
+ * recursive structure are all real.
+ *
+ * Gated by SKIP_BENCHMARKS (so `test:fast` skips it). Timing assertions are a
+ * loose catastrophic-regression ceiling only — the printed numbers are the point;
+ * hard thresholds are flaky under load (see vector-search.bench).
+ */
+import { describe, it, expect } from 'bun:test'
+import {
+  isStyleObject,
+  isColor,
+  isColorValue,
+  isDimension,
+  isAnimation,
+} from './index'
+
+/** A deterministic, realistic theme-sized style object. */
+function makeTheme(components: number): Record<string, any> {
+  const palette = [
+    '#0b5fff',
+    'rgb(16, 185, 129)',
+    'hsl(280 60% 55%)',
+    'oklch(0.7 0.15 200)',
+    'rebeccapurple',
+    'var(--brand)',
+  ]
+  const lengths = ['0', '4px', '0.5rem', '1rem', '2rem', 'calc(100% - 1rem)']
+  const theme: Record<string, any> = {
+    ':root': {
+      '--brand': '#0b5fff',
+      '--surface': 'hsl(220 20% 98%)',
+      '--text': 'rgb(17, 24, 39)',
+      '--radius': '8px',
+      '--gap': '1rem',
+      '--shadow': '0 1px 3px rgba(0,0,0,0.2)',
+      '--font': 'system-ui, sans-serif',
+    },
+  }
+  for (let i = 0; i < components; i++) {
+    theme[`.c${i}`] = {
+      color: palette[i % palette.length],
+      backgroundColor: palette[(i + 1) % palette.length],
+      padding: lengths[i % lengths.length],
+      margin: lengths[(i + 2) % lengths.length],
+      borderRadius: 'var(--radius)',
+      boxShadow: 'var(--shadow)',
+      transition: 'color 200ms ease, background 0.3s ease-in-out',
+      animation: 'spin 1s cubic-bezier(0.1, 0.7, 1, 0.1) infinite',
+      fontSize: '1rem',
+      lineHeight: '1.5',
+      '&:hover': {
+        color: palette[(i + 3) % palette.length],
+        transform: 'scale(1.02)',
+      },
+      '&:focus-visible': { outline: '2px solid var(--brand)' },
+      '@media (min-width: 640px)': { padding: '2rem' },
+    }
+  }
+  return theme
+}
+
+const bench = (label: string, iters: number, fn: () => void): number => {
+  for (let i = 0; i < Math.min(iters, 1000); i++) fn() // warm up / JIT
+  const t0 = performance.now()
+  for (let i = 0; i < iters; i++) fn()
+  const perOp = (performance.now() - t0) / iters
+  console.log(`    ${label.padEnd(34)} ${(perOp * 1000).toFixed(2)} µs/op`)
+  return perOp
+}
+
+describe.skipIf(!!process.env.SKIP_BENCHMARKS)(
+  'CSS validation perf (safe is fast)',
+  () => {
+    it('validates a theme-sized style object well under a frame', () => {
+      const theme = makeTheme(50) // ~50 rules × ~12 leaves ≈ 600 values
+      const leafCount = Object.keys(theme).length
+
+      // Correctness first — the validator must actually accept the theme…
+      expect(isStyleObject(theme)).toBe(true)
+      // …and reject a corrupted one (a selector whose value isn't a nested rule).
+      expect(isStyleObject({ ...theme, '.bad': 'not-an-object' })).toBe(false)
+
+      console.log(`\n  CSS validation (${leafCount} top-level rules):`)
+      const themeMs = bench('validate whole theme', 2000, () =>
+        isStyleObject(theme)
+      )
+      bench('isColor (per value)', 200_000, () => isColor('rgb(16, 185, 129)'))
+      bench('isColorValue (+!important)', 200_000, () =>
+        isColorValue('#3a3 !important')
+      )
+      bench('isDimension (per value)', 200_000, () => isDimension('1.5rem'))
+      bench('isAnimation (tokenize+classify)', 100_000, () =>
+        isAnimation('spin 1s cubic-bezier(0.1, 0.7, 1, 0.1) infinite')
+      )
+      // themeMs is milliseconds per theme → themes/sec = 1000 / themeMs.
+      console.log(`    → ~${Math.round(1000 / themeMs)} themes/sec\n`)
+
+      // Loose ceiling: a whole theme must validate far under one 16ms frame.
+      // (Generous 8ms tolerates CI/load; observed is a fraction of a ms.)
+      expect(themeMs).toBeLessThan(8)
+    })
+  }
+)

package/src/css/predicates.ts

@@ -0,0 +1,232 @@
+/**
+ * The CSS predicate library — canonical **source** form.
+ *
+ * Predicates are authored as source strings, not native functions, because the
+ * source is the serializable, portable artifact: it feeds the verifier
+ * (`verifyPredicate` — certifies pure/synchronous/ReDoS-clean), compiles to the
+ * native fast path (`compilePredicate`), mines autocomplete (`suggest`), and
+ * embeds into JSON Schema's `$predicate` keyword. This is the "computational
+ * half" JSON Schema and TS structural types can't express — CSS is the torture
+ * test (open value grammars, order-flexible shorthands, recursive structure).
+ *
+ * Style rules for anything added here (so it stays verifiable):
+ *   - pure & synchronous: no IO, no `await`, no `new`, no loops (use
+ *     `every`/`some`/`map`/recursion — fuel bounds them at function entry);
+ *   - regexes must be ReDoS-clean (no nested unbounded quantifiers — the
+ *     verifier rejects `(a+)+` and friends, so keep character classes flat);
+ *   - compose with `||` and named predicates as callbacks (`toks.every(isX)`).
+ *
+ * Phase 1 ships the color grammar. Later phases add lengths/dimensions,
+ * shorthands, and the recursive style-object structure — see TODO.md (#4).
+ */
+
+/**
+ * The CSS Color Module Level 4 named colors (+ the CSS-wide `transparent` and
+ * `currentcolor`), lower-cased. Data, kept in the source so the whole cluster
+ * stays serializable as one artifact.
+ */
+export const CSS_NAMED_COLORS = [
+  'transparent',
+  'currentcolor',
+  'aliceblue',
+  'antiquewhite',
+  'aqua',
+  'aquamarine',
+  'azure',
+  'beige',
+  'bisque',
+  'black',
+  'blanchedalmond',
+  'blue',
+  'blueviolet',
+  'brown',
+  'burlywood',
+  'cadetblue',
+  'chartreuse',
+  'chocolate',
+  'coral',
+  'cornflowerblue',
+  'cornsilk',
+  'crimson',
+  'cyan',
+  'darkblue',
+  'darkcyan',
+  'darkgoldenrod',
+  'darkgray',
+  'darkgreen',
+  'darkgrey',
+  'darkkhaki',
+  'darkmagenta',
+  'darkolivegreen',
+  'darkorange',
+  'darkorchid',
+  'darkred',
+  'darksalmon',
+  'darkseagreen',
+  'darkslateblue',
+  'darkslategray',
+  'darkslategrey',
+  'darkturquoise',
+  'darkviolet',
+  'deeppink',
+  'deepskyblue',
+  'dimgray',
+  'dimgrey',
+  'dodgerblue',
+  'firebrick',
+  'floralwhite',
+  'forestgreen',
+  'fuchsia',
+  'gainsboro',
+  'ghostwhite',
+  'gold',
+  'goldenrod',
+  'gray',
+  'green',
+  'greenyellow',
+  'grey',
+  'honeydew',
+  'hotpink',
+  'indianred',
+  'indigo',
+  'ivory',
+  'khaki',
+  'lavender',
+  'lavenderblush',
+  'lawngreen',
+  'lemonchiffon',
+  'lightblue',
+  'lightcoral',
+  'lightcyan',
+  'lightgoldenrodyellow',
+  'lightgray',
+  'lightgreen',
+  'lightgrey',
+  'lightpink',
+  'lightsalmon',
+  'lightseagreen',
+  'lightskyblue',
+  'lightslategray',
+  'lightslategrey',
+  'lightsteelblue',
+  'lightyellow',
+  'lime',
+  'limegreen',
+  'linen',
+  'magenta',
+  'maroon',
+  'mediumaquamarine',
+  'mediumblue',
+  'mediumorchid',
+  'mediumpurple',
+  'mediumseagreen',
+  'mediumslateblue',
+  'mediumspringgreen',
+  'mediumturquoise',
+  'mediumvioletred',
+  'midnightblue',
+  'mintcream',
+  'mistyrose',
+  'moccasin',
+  'navajowhite',
+  'navy',
+  'oldlace',
+  'olive',
+  'olivedrab',
+  'orange',
+  'orangered',
+  'orchid',
+  'palegoldenrod',
+  'palegreen',
+  'paleturquoise',
+  'palevioletred',
+  'papayawhip',
+  'peachpuff',
+  'peru',
+  'pink',
+  'plum',
+  'powderblue',
+  'purple',
+  'rebeccapurple',
+  'red',
+  'rosybrown',
+  'royalblue',
+  'saddlebrown',
+  'salmon',
+  'sandybrown',
+  'seagreen',
+  'seashell',
+  'sienna',
+  'silver',
+  'skyblue',
+  'slateblue',
+  'slategray',
+  'slategrey',
+  'snow',
+  'springgreen',
+  'steelblue',
+  'tan',
+  'teal',
+  'thistle',
+  'tomato',
+  'turquoise',
+  'violet',
+  'wheat',
+  'white',
+  'whitesmoke',
+  'yellow',
+  'yellowgreen',
+]
+
+/**
+ * Color predicate cluster (source). Entry points: `isColor` (any CSS color) and
+ * `isColorValue` (a color, tolerating a trailing `!important`). Regexes are
+ * flat-class (ReDoS-clean). The functional-color forms (`hwb`/`lab`/`lch`/
+ * `oklab`/`oklch`/`color`/`color-mix`) are matched by name + balanced parens
+ * rather than validating their args — precise enough for validation, open
+ * enough not to reject valid modern CSS.
+ */
+export const CSS_COLOR_SOURCE = `
+var CSS_NAMED_COLORS = ${JSON.stringify(CSS_NAMED_COLORS)}
+
+function isNamedColor(v) {
+  return typeof v === 'string' && CSS_NAMED_COLORS.includes(v.toLowerCase())
+}
+function isHexColor(v) {
+  return typeof v === 'string' && /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(v)
+}
+function isRgbColor(v) {
+  return typeof v === 'string' && /^rgba?\\(\\s*[-0-9.,%\\s/]+\\)$/i.test(v)
+}
+function isHslColor(v) {
+  return typeof v === 'string' && /^hsla?\\(\\s*[-0-9.,%\\s/adegr]+\\)$/i.test(v)
+}
+function isColorFn(v) {
+  if (typeof v !== 'string' || !v.endsWith(')')) { return false }
+  return v.startsWith('hwb(') || v.startsWith('lab(') || v.startsWith('lch(')
+      || v.startsWith('oklab(') || v.startsWith('oklch(')
+      || v.startsWith('color(') || v.startsWith('color-mix(')
+}
+function isColorVar(v) {
+  return typeof v === 'string' && v.startsWith('var(--') && v.endsWith(')')
+}
+function isColor(v) {
+  return isNamedColor(v) || isHexColor(v) || isRgbColor(v)
+      || isHslColor(v) || isColorFn(v) || isColorVar(v)
+}
+function isColorValue(v) {
+  if (typeof v !== 'string') { return false }
+  var bare = v.replace(/\\s*!important\\s*$/i, '')
+  return isColor(bare)
+}
+`
+
+/** Entry predicates exported by the color cluster (for compile/suggest). */
+export const CSS_COLOR_ENTRIES = [
+  'isColor',
+  'isColorValue',
+  'isNamedColor',
+  'isHexColor',
+  'isRgbColor',
+  'isHslColor',
+] as const

package/src/css/property-aware.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Property-aware validation — `isStyleValueFor(prop, val)` tightens the closed
+ * value grammars (color/animation/transition) so `isStyleObject` catches real
+ * value errors (`color: 'notacolor'`), while keyword-heavy properties stay
+ * permissive (no false rejections). This is the "validates real style objects"
+ * payoff over structure-only checking.
+ */
+import { describe, it, expect } from 'bun:test'
+import { isStyleValueFor, isStyleObject } from './index'
+
+describe('isStyleValueFor — closed grammars are enforced', () => {
+  it('color: precise (rejects a non-color)', () => {
+    expect(isStyleValueFor('color', 'red')).toBe(true)
+    expect(isStyleValueFor('color', '#3a3')).toBe(true)
+    expect(isStyleValueFor('color', 'notacolor')).toBe(false)
+    expect(isStyleValueFor('color', 5)).toBe(false)
+  })
+  it('color: kebab-case and camelCase both normalize', () => {
+    expect(isStyleValueFor('background-color', 'blue')).toBe(true)
+    expect(isStyleValueFor('backgroundColor', 'blue')).toBe(true)
+    expect(isStyleValueFor('borderTopColor', 'nope')).toBe(false)
+  })
+  it('animation / transition: precise', () => {
+    expect(isStyleValueFor('animation', 'spin 1s ease infinite')).toBe(true)
+    expect(isStyleValueFor('animation', 'spin 1s @@@')).toBe(false)
+    expect(isStyleValueFor('transition', 'all 0.3s ease')).toBe(true)
+    expect(isStyleValueFor('transition', 'color 200ms @@@')).toBe(false)
+  })
+})
+
+describe('isStyleValueFor — universal escapes valid on any property', () => {
+  for (const v of [
+    'inherit',
+    'initial',
+    'unset',
+    'var(--x)',
+    'calc(1px + 2px)',
+  ]) {
+    it(`color accepts ${v}`, () =>
+      expect(isStyleValueFor('color', v)).toBe(true))
+  }
+})
+
+describe('isStyleValueFor — keyword-heavy properties stay permissive', () => {
+  it('width/padding/display accept idents we do not enumerate', () => {
+    expect(isStyleValueFor('width', 'fit-content')).toBe(true)
+    expect(isStyleValueFor('padding', '10px 1rem')).toBe(true)
+    expect(isStyleValueFor('display', 'flex')).toBe(true)
+    expect(isStyleValueFor('fontWeight', 'bold')).toBe(true)
+    expect(isStyleValueFor('zIndex', 10)).toBe(true)
+  })
+  it('but still rejects empty / non-primitive', () => {
+    expect(isStyleValueFor('padding', '')).toBe(false)
+    expect(isStyleValueFor('padding', {})).toBe(false)
+  })
+})
+
+describe('isStyleObject now catches value errors, not just structure', () => {
+  it('rejects a bad color where structure is fine', () => {
+    expect(isStyleObject({ color: 'red', padding: '10px' })).toBe(true)
+    expect(isStyleObject({ color: 'notacolor' })).toBe(false)
+    expect(isStyleObject({ backgroundColor: 'bogus' })).toBe(false)
+  })
+  it('catches a bad color inside a nested selector', () => {
+    expect(isStyleObject({ '&:hover': { color: 'nope' } })).toBe(false)
+    expect(isStyleObject({ '&:hover': { color: 'blue' } })).toBe(true)
+  })
+  it('catches a bad animation shorthand', () => {
+    expect(isStyleObject({ animation: 'spin 1s @@@' })).toBe(false)
+    expect(isStyleObject({ animation: 'spin 1s ease' })).toBe(true)
+  })
+  it('still accepts a full realistic spec (permissive where it should be)', () => {
+    expect(
+      isStyleObject({
+        color: 'var(--text)',
+        padding: '1rem 2rem',
+        display: 'grid',
+        boxShadow: '0 1px 2px rgba(0,0,0,0.2)',
+        transition: 'color 200ms ease',
+        '&:hover': { color: '#00f' },
+      })
+    ).toBe(true)
+  })
+})

package/src/css/shorthands.test.ts

@@ -0,0 +1,90 @@
+/**
+ * `tjs-lang/css` phase 3 — order-flexible shorthands (animation, transition).
+ * The torture case: tokens in any order. Same vertical slice — the source
+ * verifies safe (via `verifyCss`, all clusters) and compiles to correct
+ * validators; the `$predicate` schemas validate the shorthand grammar.
+ */
+import { describe, it, expect } from 'bun:test'
+import { validatePredicateSchema } from '../lang/predicate-schema'
+import {
+  isAnimation,
+  isTransition,
+  isTimingFunction,
+  cssAnimationSchema,
+  cssTransitionSchema,
+  verifyCss,
+} from './index'
+
+describe('all clusters (incl. shorthands) are predicate-safe', () => {
+  it('verifyCss covers the shorthand cluster', () => {
+    const r = verifyCss()
+    if (!r.safe) console.error(r.diagnostics)
+    expect(r.safe).toBe(true)
+  })
+})
+
+describe('isAnimation — order-free tokens', () => {
+  const valid = [
+    '3s ease-in 1s infinite alternate slidein', // the PoC example
+    'slidein 3s ease-in', // reordered
+    'infinite alternate 3s slidein', // heavily reordered
+    '1s linear',
+    '200ms',
+    'spin 1s cubic-bezier(0.1, 0.7, 1, 0.1) infinite',
+    'spin 1s steps(4, end)',
+    'var(--motion)',
+    'slide 2s, fade 1s ease-out', // comma-separated list
+  ]
+  for (const v of valid)
+    it(`accepts ${v}`, () => expect(isAnimation(v)).toBe(true))
+
+  const invalid = [
+    '3s @@@', // junk token
+    '', // empty
+    'slide 2s,', // trailing empty layer
+    42,
+    null,
+  ]
+  for (const v of invalid)
+    it(`rejects ${JSON.stringify(v)}`, () => expect(isAnimation(v)).toBe(false))
+})
+
+describe('isTransition', () => {
+  it('accepts', () => {
+    expect(isTransition('all 0.3s ease')).toBe(true)
+    expect(isTransition('color 200ms linear, background 1s')).toBe(true)
+    expect(isTransition('opacity 0.2s ease-in-out 0.1s')).toBe(true)
+    expect(isTransition('none')).toBe(true)
+  })
+  it('rejects', () => {
+    expect(isTransition('color 200ms @@@')).toBe(false)
+    expect(isTransition('')).toBe(false)
+  })
+})
+
+describe('isTimingFunction', () => {
+  it('keywords + functions', () => {
+    for (const t of ['linear', 'ease-in-out', 'step-start'])
+      expect(isTimingFunction(t)).toBe(true)
+    expect(isTimingFunction('cubic-bezier(0.1, 0.7, 1, 0.1)')).toBe(true)
+    expect(isTimingFunction('steps(4, end)')).toBe(true)
+    expect(isTimingFunction('linear(0, 0.5, 1)')).toBe(true)
+    expect(isTimingFunction('wobble')).toBe(false)
+  })
+})
+
+describe('$predicate schemas', () => {
+  it('cssAnimationSchema validates via the entry alias', () => {
+    expect(
+      validatePredicateSchema(cssAnimationSchema(), '1s ease infinite').valid
+    ).toBe(true)
+    expect(validatePredicateSchema(cssAnimationSchema(), '1s @@@').valid).toBe(
+      false
+    )
+  })
+  it('cssTransitionSchema', () => {
+    expect(
+      validatePredicateSchema(cssTransitionSchema(), 'all 0.3s ease').valid
+    ).toBe(true)
+  })
+})

package/src/css/shorthands.ts

@@ -0,0 +1,113 @@
+/**
+ * CSS order-flexible shorthands (phase 3) — the second torture case from the
+ * PoC: a shorthand like `animation` or `transition` is a comma-separated list of
+ * layers, each a whitespace-separated bag of tokens whose *order is free*
+ * (`3s ease-in 1s infinite alternate slidein` ≡ any permutation). TS unions and
+ * JSON Schema can't express "a set of tokens, each classifiable, in any order";
+ * a predicate tokenizes and classifies (`toks.every(isAnimToken)`).
+ *
+ * Built on the dimension leaf cluster (for `isTime`/`isCssVar`/`isCssCalc`).
+ * Same rules as the other clusters: pure, synchronous, ReDoS-clean (the split
+ * regexes are single-quantifier `\s+` / `,`; classifier regexes are flat).
+ */
+import type { PredicateSchema } from '../lang/predicate-schema'
+import { CSS_DIMENSION_SOURCE } from './dimensions'
+
+/**
+ * The shorthand classifiers alone (no leaf cluster prepended). Exported so the
+ * combined style cluster (`style.ts`) can compose them for property-aware
+ * validation without re-including the dimension source.
+ */
+export const CSS_SHORTHAND_FRAGMENT = `
+var ANIM_TIMING = ['linear','ease','ease-in','ease-out','ease-in-out','step-start','step-end']
+var ANIM_DIRECTION = ['normal','reverse','alternate','alternate-reverse']
+var ANIM_FILLMODE = ['none','forwards','backwards','both']
+var ANIM_PLAYSTATE = ['running','paused']
+
+function isTimingFunction(t) {
+  if (typeof t !== 'string') { return false }
+  if (ANIM_TIMING.includes(t)) { return true }
+  return (t.startsWith('cubic-bezier(') || t.startsWith('steps(') || t.startsWith('linear(')) && t.endsWith(')')
+}
+function isIterationCount(t) {
+  return t === 'infinite' || (typeof t === 'string' && /^[0-9]*\\.?[0-9]+$/.test(t))
+}
+function isAnimName(t) {
+  // any custom-ident (also matches keywords, which classify earlier anyway)
+  return typeof t === 'string' && /^-?[a-z_][a-z0-9_-]*$/i.test(t)
+}
+// Tokenize a whole shorthand value. A function token like cubic-bezier(a, b) is
+// kept whole (arg spaces/commas must not split it); top-level commas (layer
+// separators) and whitespace are delimiters, so they're dropped. Loops are
+// banned in predicates, so this is one .match with a FLAT (ReDoS-clean) regex —
+// note a paren-aware comma *splitter* would be a nested quantifier the verifier
+// rejects, so we tokenize instead and guard empty layers separately.
+function cssTokens(v) {
+  return typeof v === 'string' ? v.match(/[a-z-]+\\([^)]*\\)|[^\\s,]+/gi) : null
+}
+// Reject leading/trailing/double commas (empty layers). Flat, ReDoS-clean.
+function hasEmptyLayer(v) {
+  return typeof v === 'string' && /^\\s*,|,\\s*$|,\\s*,/.test(v)
+}
+function isAnimToken(t) {
+  return isTime(t) || isIterationCount(t) || isTimingFunction(t)
+      || ANIM_DIRECTION.includes(t) || ANIM_FILLMODE.includes(t) || ANIM_PLAYSTATE.includes(t)
+      || isCssVar(t) || isCssCalc(t) || isAnimName(t)
+}
+function isAnimation(v) {
+  if (typeof v !== 'string' || v.length === 0 || hasEmptyLayer(v)) { return false }
+  var toks = cssTokens(v)
+  return toks !== null && toks.length > 0 && toks.every(isAnimToken)
+}
+
+function isTransitionProperty(t) {
+  return t === 'all' || t === 'none' || isAnimName(t)
+}
+function isTransitionToken(t) {
+  return isTime(t) || isTimingFunction(t) || isCssVar(t) || isCssCalc(t) || isTransitionProperty(t)
+}
+function isTransition(v) {
+  if (typeof v !== 'string' || v.length === 0 || hasEmptyLayer(v)) { return false }
+  var toks = cssTokens(v)
+  return toks !== null && toks.length > 0 && toks.every(isTransitionToken)
+}
+`
+
+/**
+ * Shorthand predicate cluster (source) = dimension leaves + the shorthand
+ * classifiers. Entry predicates: `isAnimation`, `isTransition` (each accepts a
+ * comma-separated list of order-free token layers).
+ */
+export const CSS_SHORTHAND_SOURCE =
+  CSS_DIMENSION_SOURCE + '\n' + CSS_SHORTHAND_FRAGMENT
+
+/** Entry predicates exported by the shorthand cluster (for compile/verify). */
+export const CSS_SHORTHAND_ENTRIES = [
+  'isTimingFunction',
+  'isAnimation',
+  'isTransition',
+] as const
+
+/**
+ * A `$predicate` schema for a CSS `animation` shorthand value (entry
+ * `isAnimation`). Uses the full cluster source so the entry (last function) is
+ * `isTransition` — so pin the entry via a wrapper source ending in `isAnimation`.
+ */
+function schemaFor(entry: string): PredicateSchema {
+  // The `$predicate` entry is the LAST function; append a thin alias so `entry`
+  // is last regardless of its position in the cluster.
+  return {
+    type: 'string',
+    $predicate: `${CSS_SHORTHAND_SOURCE}\nfunction __entry(v) { return ${entry}(v) }`,
+  }
+}
+
+/** `$predicate` schema for a CSS `animation` shorthand value. */
+export function cssAnimationSchema(): PredicateSchema {
+  return { ...schemaFor('isAnimation'), title: 'CSSAnimation' }
+}
+
+/** `$predicate` schema for a CSS `transition` shorthand value. */
+export function cssTransitionSchema(): PredicateSchema {
+  return { ...schemaFor('isTransition'), title: 'CSSTransition' }
+}