@starci/hfs 4.7.34 → 4.7.36

package/runtime/scripts/hfs/grammar-presentation.mjs

@@ -0,0 +1,152 @@
+// Family presentation data decorates universal proof cases without moving their semantic identities.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { openHfs } from './slots.mjs';
+import { grammarFamilyFor } from '../lib/grammar-lint.mjs';
+
+const GRAMMARS = fileURLToPath(new URL('../../knowledge/grammars/', import.meta.url));
+const PADDING_TOPIC = 'presentation/padding.yaml';
+const TOPIC_NAMES = ['padding', 'font'];
+const REM_PX = 16;
+const TEXT_WEIGHT_NAMES = ['normal', 'medium', 'semibold'];
+
+/** The Common text-weight matrix is complete only when each public weight has one declared class. */
+function fontWeightClasses(guidance) {
+  const matrix = guidance?.familyRequirement ?? guidance?.requirement ?? '';
+  const pattern = new RegExp('`font-(' + TEXT_WEIGHT_NAMES.join('|') + ')`', 'g');
+  const names = [...String(matrix).matchAll(pattern)].map(match => match[1]);
+  if (names.length !== TEXT_WEIGHT_NAMES.length || new Set(names).size !== TEXT_WEIGHT_NAMES.length) {
+    throw new Error('Grammar font weight matrix is missing or incomplete');
+  }
+  return names;
+}
+
+/** Resolve a recorded rem, px or unitless scale value at the proof's baseline root; unsupported values stay unavailable. */
+export const remPx = (value) => {
+  const match = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(rem|px)?$/.exec(String(value ?? '').trim());
+  if (!match) return null;
+  const px = Number(match[1]) * (match[2] === 'px' ? 1 : REM_PX);
+  return Number.isFinite(px) ? px : null;
+};
+
+/** Resolve the selected family's published text weights through the active CSS token scope. */
+export function fontWeightsOf(guidance, scope) {
+  const weights = fontWeightClasses(guidance).map(name => Number(scope?.variable(`--font-weight-${name}`)?.value));
+  if (weights.some(weight => !Number.isFinite(weight))) throw new Error('Grammar font weight tokens are unresolved');
+  return weights;
+}
+
+/** Missing or ambiguous family weight data cannot remove the render's weight proof. */
+function validateFontGuidance(data) {
+  const weights = (data.guidance ?? []).filter(item => item.id === 'weight');
+  if (weights.length !== 1) throw new Error('Grammar font guidance needs one concrete weight matrix');
+  fontWeightClasses(weights[0]);
+}
+
+/** Read the explicit family or the app declaration; CSS discovery never chooses presentation law. */
+function selectedFamily(family, repo) {
+  if (family !== null && family !== undefined) return grammarFamilyFor(family).id;
+  if (!repo) throw new Error('Presentation proof needs an explicit Grammar family or an app repository');
+  const declaration = openHfs({ root: skillRoot, repoRoot: repo }).repo;
+  return grammarFamilyFor(declaration.grammar ?? declaration.sides?.fe?.grammar).id;
+}
+
+/** The one declared presentation owner, following only explicit inheritance and rejecting cycles. */
+function presentationOwner(family, name, seen = new Set()) {
+  if (seen.has(family)) throw new Error(`Grammar ${name} inheritance cycles at ${family}`);
+  seen.add(family);
+  const entry = grammarFamilyFor(family);
+  if (typeof entry.productComposition !== 'string' || !entry.productComposition) {
+    throw new Error(`Grammar family ${family} has no presentation playbook`);
+  }
+  const file = path.resolve(GRAMMARS, entry.productComposition);
+  const relative = path.relative(GRAMMARS, file);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`Grammar family ${family} has an invalid presentation path`);
+  const doc = parseYaml(fs.readFileSync(file, 'utf8'));
+  const data = doc?.presentation?.[name];
+  if (!data || typeof data !== 'object') throw new Error(`Grammar family ${family} has no ${name} presentation data`);
+  if (Object.hasOwn(data, 'inherits')) {
+    if (Object.keys(data).some(key => !['inherits', 'ownership', 'contract'].includes(key))) {
+      throw new Error(`Grammar family ${family} mixes inherited and replacement ${name} data`);
+    }
+    return presentationOwner(data.inherits, name, seen);
+  }
+  if (!Array.isArray(data.scale?.steps) || !data.scale.steps.length
+    || !Array.isArray(data.componentOwnership?.rows) || !data.componentOwnership.rows.length
+    || !Array.isArray(data.recipes) || !data.recipes.length) {
+    throw new Error(`Grammar family ${family} has incomplete ${name} presentation data`);
+  }
+  const steps = new Map(data.scale.steps.map(step => [step.id, step]));
+  if (steps.size !== data.scale.steps.length || data.scale.steps.some(step => typeof step.id !== 'string'
+    || !step.id || (name === 'padding' && (remPx(step.value) === null || remPx(step.value) < 0)))) {
+    throw new Error(`Grammar family ${family} has duplicate or unusable ${name} scale steps`);
+  }
+  if (data.componentOwnership.rows.some(row => !steps.has(row.rule))) {
+    throw new Error(`Grammar family ${family} has a component ${name === 'padding' ? 'inset' : 'font rank'} without a scale value`);
+  }
+  if (data.recipes.some(recipe => typeof recipe.title !== 'string' || !recipe.title.trim())) {
+    throw new Error(`Grammar family ${family} has a ${name} recipe without its concrete title`);
+  }
+  if (name === 'font') validateFontGuidance(data);
+  return { data, source: `knowledge/grammars/${relative.split(path.sep).join('/')}#presentation.${name}` };
+}
+
+/** Preserve every universal case while attaching the exact renderer recipe and its numerical owner. */
+function presentationTopic(topic, owner, name) {
+  const { data, source } = owner;
+  const recipes = new Map(data.recipes.map(recipe => [recipe.rule, recipe]));
+  const rules = topic.doc.rules ?? [];
+  if (recipes.size !== data.recipes.length || recipes.size !== rules.length) {
+    throw new Error(`Grammar ${name} recipes do not cover the universal rule identities exactly once`);
+  }
+  const attached = rules.map(rule => {
+    const recipe = recipes.get(rule.id);
+    const byCase = new Map((recipe?.cases ?? []).map(item => [item.id, item]));
+    if (!recipe || byCase.size !== recipe.cases.length || byCase.size !== (rule.cases ?? []).length) {
+      throw new Error(`Grammar ${name} recipe ${rule.id} does not cover its universal cases exactly once`);
+    }
+    const cases = rule.cases.map(item => {
+      const concrete = byCase.get(item.id);
+      if (!concrete || typeof concrete.render !== 'string' || typeof concrete.owner !== 'string') {
+        throw new Error(`Grammar ${name} recipe ${rule.id}/${item.id} has no renderer contract`);
+      }
+      return { ...item, owner: concrete.owner, render: concrete.render, recipeSource: source };
+    });
+    return { ...rule, familyTitle: recipe.title, cases };
+  });
+  const guidance = new Map((topic.doc.guidance ?? []).map(item => [item.id, item]));
+  for (const concrete of data.guidance ?? []) {
+    const semantic = guidance.get(concrete.id);
+    guidance.set(concrete.id, semantic ? { ...semantic, familyRequirement: concrete.requirement, familySource: source }
+      : { ...concrete, familySource: source });
+  }
+  return {
+    ...topic,
+    familySource: source,
+    doc: { ...topic.doc, scale: data.scale, componentOwnership: data.componentOwnership,
+      guidance: [...guidance.values()], rules: attached },
+  };
+}
+
+/**
+ * Bind supported universal presentation cases to the selected family's numerical recipes without mutation.
+ * Missing family data and incomplete coverage fail visibly rather than selecting another family.
+ * @param {object[]} knowledge - Universal topics with stable relative paths and parsed documents.
+ * @param {{ family?: string, repo?: string }} input - Explicit family or the app whose declaration selects it.
+ * @returns {{ family: string, knowledge: object[] }} Selected family and proof-ready topics with owner provenance.
+ */
+export function familyPresentationKnowledge(knowledge, { family = null, repo = null } = {}) {
+  const selected = selectedFamily(family, repo);
+  const topics = knowledge.filter(topic => topic.rel.endsWith(PADDING_TOPIC));
+  if (topics.length !== 1) throw new Error('Presentation proof needs exactly one universal padding topic');
+  const decorated = new Map();
+  for (const name of TOPIC_NAMES) {
+    const matches = knowledge.filter(topic => topic.rel.endsWith(`presentation/${name}.yaml`));
+    if (matches.length > 1) throw new Error(`Presentation proof has duplicate universal ${name} topics`);
+    if (matches.length) decorated.set(matches[0], presentationTopic(matches[0], presentationOwner(selected, name), name));
+  }
+  return { family: selected, knowledge: knowledge.map(topic => decorated.get(topic) ?? topic) };
+}

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -12,7 +12,7 @@ import { fail } from './slot-errors.mjs';
 
 const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
 const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
-const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'eslint-grammar-starci', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
 const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
 const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -346,7 +346,7 @@ export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_R
     /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
     lintCode: (ruleId) => {
       const [plugin, id] = String(ruleId ?? '').split('/');
-      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || null;
+      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || (plugin === 'starci-grammar' && 'eslint-grammar-starci') || null;
       return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
     },
     /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -42,6 +42,7 @@ import { feBuildArgsFindings } from './fe-build-args.mjs';
 /** The failure codes the finders above emit, so `starci app check` ships their labels (check.mjs adds them to CHECK_CODES). Append-only; the coordinator regenerates it at merge time. */
 export const A15_CODES = [
   // codes-begin
+  'FE_STACK_FAMILY_LINT_MISSING',
   'HFS_TEXT_CORRUPT',
   'FE_PUBLIC_BUILD_ARG_MISSING',
   'HFS_WORKFLOW_CONTEXT',

package/runtime/scripts/hfs/rules/fe-stack.mjs

@@ -12,10 +12,15 @@ import { found, readJson } from './read.mjs';
 import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
 import { editionRuleParams } from '../edition-slots.mjs';
 import { globExpression } from '../../lib/glob.mjs';
+import { grammarLintFor } from '../../lib/grammar-lint.mjs';
+import { numericMatch } from '../../lib/numeric-match.mjs';
 
 export const FE_STACK_FORBIDDEN = 'FE_STACK_FORBIDDEN';
 export const FE_STACK_UNLISTED = 'FE_STACK_UNLISTED';
 export const FE_STACK_CORE_MISSING = 'FE_STACK_CORE_MISSING';
+export const FE_STACK_FAMILY_LINT_MISSING = 'FE_STACK_FAMILY_LINT_MISSING';
+const UNIVERSAL_CANON = '@starci/eslint-canon-fe';
+const FAMILY_SPLIT_MAJOR = 9;
 const CATALOG_FILE = new URL('../../../knowledge/hfs/fe-stack.yaml', import.meta.url);
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
 const APP_ROOT_MANIFEST = 'package.json';
@@ -109,6 +114,42 @@ function unlistedFindings(rel, pkg, allowed, extras, workspaces) {
   return findings;
 }
 
+/** The major version a dependency spec admits, or null when the spec names no plain semver (a tag, a path or a protocol). */
+const declaredMajor = (spec) => numericMatch(spec, /^[\^~>=v\s]*(\d+)(?:\.|$)/);
+
+/** The universal canon's declared spec in any front-end or app-root manifest, or null when none declares it. */
+function universalCanonSpec(manifests) {
+  for (const [, pkg] of manifests) for (const section of DEPENDENCY_SECTIONS) {
+    const spec = pkg?.[section]?.[UNIVERSAL_CANON];
+    if (spec !== undefined) return spec;
+  }
+  return null;
+}
+
+/**
+ * From canon-fe 9 the Grammar component rules ship in the selected family's lint package; an app that installs the
+ * universal canon without that package would silently lose them, so the stack refuses it. An unparseable spec is judged
+ * like 9 rather than waved through.
+ */
+function familyLintFindings(declaration, repo, packages, rootManifest) {
+  const family = declaration?.sides?.fe?.grammar ?? repo.grammar;
+  if (typeof family !== 'string' || !family) return [];
+  const manifests = [...packages, ['../package.json', rootManifest]];
+  const product = (repo.apps ?? []).find(app => app.kind === 'next' && app.name !== 'landing');
+  const anchor = product ? `apps/${product.name}/package.json` : 'package.json';
+  const spec = universalCanonSpec(manifests);
+  if (spec === null) return [];
+  const major = declaredMajor(spec);
+  if (major !== null && major < FAMILY_SPLIT_MAJOR) return [];
+  const lint = grammarLintFor(family);
+  if (lint.package === null) return [];
+  if (manifests.some(([, pkg]) => dependenciesOf(pkg).has(lint.package))) return [];
+  const nextStep = `Add ${lint.package} beside ${UNIVERSAL_CANON} (the app root devDependencies or the fe workspace), compose ${lint.factory}({ hfs }) after starciFeConfig({ hfs }) in fe/eslint.config.mjs, or run starci app sync.`;
+  return [found(FE_STACK_FAMILY_LINT_MISSING, anchor,
+    `hfs.json selects sides.fe.grammar ${family} and the front end declares ${UNIVERSAL_CANON} ${spec}, but no manifest declares ${lint.package}: from ${UNIVERSAL_CANON} ${FAMILY_SPLIT_MAJOR} that package carries the ${family} Grammar component rules, so without it they are not enforced. ${nextStep}`,
+    { dependency: lint.package, family, nextStep })];
+}
+
 /** Closed FE catalog and core presence over the front-end side (the mixed root also holds BE tools). */
 export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, inScope = () => true }) {
   if (repo.profile !== 'fe' || repo.kind === 'runtime') return [];
@@ -119,7 +160,9 @@ export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, i
   const { allowed, core } = stackCatalog();
   const extras = extraPackages(declaration);
   const findings = [...packages].filter(([file]) => inScope(file)).flatMap(([file, pkg]) => unlistedFindings(file, pkg, allowed, extras, workspaces));
-  const rootTools = dependenciesOf(readJson(repoRoot, '../package.json'));
+  const rootManifest = readJson(repoRoot, '../package.json');
+  const rootTools = dependenciesOf(rootManifest);
+  findings.push(...familyLintFindings(declaration, repo, packages, rootManifest));
   for (const app of repo.apps ?? []) {
     if (app.kind !== 'next' || app.name === 'landing') continue;
     const rel = `apps/${app.name}/package.json`;

package/runtime/scripts/hfs/slots.mjs

@@ -120,6 +120,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
     connections: Object.freeze((s.connections ?? []).map(connectionView)),
     providers,
     reads: Object.freeze([...(s.reads ?? [])]),
+    ...(s.grammar === undefined ? {} : { grammar: s.grammar }),
     ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
     manifestVersion: manifest.version,
   });

package/runtime/scripts/hfs/view.mjs

@@ -33,6 +33,7 @@ function hfsView(opened, repoRoot) {
     profile: opened.repo.profile,
     side: opened.repo.side ?? null,
     edition: opened.repo.edition ?? 'full',
+    ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
     apps: opened.repo.apps,
     connections: opened.repo.connections,
     patterns: Object.freeze([...(opened.repo.patterns ?? [])]),

package/runtime/scripts/lib/canon-binding-text.mjs

@@ -0,0 +1,129 @@
+// Canon release binding edits preserve authored profile text and update only the selected binding's identity.
+
+const KEY = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function supportedBinding(value) {
+  const keys = typeof value === 'string' ? value.split('.') : [];
+  return (keys.length === 1 && keys[0] === 'canon') || (keys.length === 2 && keys[0] === 'familyCanons' && KEY.test(keys[1]));
+}
+
+function lineEntry(line, index) {
+  const text = line.slice(0, line.length - lineEnding(line).length);
+  if (!text.trim() || text.trimStart().startsWith('#')) return null;
+  let indent = 0;
+  while (text[indent] === ' ') indent++;
+  const colon = text.indexOf(':', indent);
+  const key = colon < 0 ? '' : text.slice(indent, colon);
+  if (!KEY.test(key)) return { index, indent };
+  let valueAt = colon + 1;
+  while (text[valueAt] === ' ' || text[valueAt] === '\t') valueAt++;
+  return { index, indent, key, prefix: text.slice(0, valueAt), value: text.slice(valueAt) };
+}
+
+function lineEnding(line) {
+  if (line.endsWith('\r\n')) return '\r\n';
+  return line.endsWith('\n') ? '\n' : '';
+}
+
+function linesOf(text) {
+  const lines = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index++) {
+    if (text[index] !== '\n') continue;
+    lines.push(text.slice(start, index + 1));
+    start = index + 1;
+  }
+  if (start < text.length) lines.push(text.slice(start));
+  return lines;
+}
+
+function child(entries, parent, key, at) {
+  const nested = entries.filter(entry => entry.index > parent.start && entry.index < parent.end && entry.indent > parent.indent);
+  const directIndent = Math.min(...nested.map(entry => entry.indent));
+  const found = nested.filter(entry => entry.indent === directIndent && entry.key === key);
+  if (found.length !== 1) throw new Error(`${at}: expected one ${key} field, found ${found.length}`);
+  const entry = found[0];
+  const boundary = entries.find(candidate => candidate.index > entry.index && candidate.index < parent.end && candidate.indent <= entry.indent);
+  return { ...entry, start: entry.index, end: boundary?.index ?? parent.end };
+}
+
+function mapping(entries, parent, key, at) {
+  const node = child(entries, parent, key, at);
+  if (node.value.trim() && !node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a block mapping`);
+  return node;
+}
+
+function scalar(entries, parent, key, at) {
+  const node = child(entries, parent, key, at);
+  if (!node.value.trim() || node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a scalar value`);
+  return node;
+}
+
+function scalarParts(value) {
+  const quote = value[0] === "'" || value[0] === '"' ? value[0] : null;
+  let end = quote ? value.indexOf(quote, 1) : 0;
+  if (quote && end < 1) return null;
+  if (quote) end++;
+  else {
+    while (end < value.length && value[end].trim() && !['#', "'", '"'].includes(value[end])) end++;
+  }
+  if (!end) return null;
+  let tail = end;
+  while (value[tail] === ' ' || value[tail] === '\t') tail++;
+  if (tail < value.length && (tail === end || value[tail] !== '#')) return null;
+  return { value: quote ? value.slice(1, end - 1) : value.slice(0, end), suffix: value.slice(end) };
+}
+
+function packageValue(value) {
+  return scalarParts(value)?.value;
+}
+
+function replaceScalar(lines, node, value) {
+  const parts = scalarParts(node.value);
+  if (!parts) throw new Error(`Cannot replace malformed scalar ${node.key}`);
+  lines[node.index] = `${node.prefix}${value}${parts.suffix}${lineEnding(lines[node.index])}`;
+}
+
+function bindingNode(entries, root, row) {
+  const at = `profiles.${row.profile}.${row.binding}`;
+  let node = mapping(entries, root, 'profiles', 'document');
+  node = mapping(entries, node, row.profile, 'profiles');
+  for (const key of row.binding.split('.')) node = mapping(entries, node, key, at);
+  const declared = scalar(entries, node, 'package', at);
+  if (packageValue(declared.value) !== row.package) throw new Error(`${at}: package does not match ${row.package}`);
+  return { node, at };
+}
+
+/**
+ * Render release version and digest updates at their exact profile binding paths without reserializing authored YAML.
+ * Unrelated bytes, comments and newline style are preserved. Missing or duplicate mapping paths, unexpected packages,
+ * incomplete digest blocks and invalid replacement identities throw before any caller writes the returned text.
+ * @param {string} original - The authored code-pattern profile YAML.
+ * @param {Array<{profile: string, binding: string, package: string, to: {version: string, value: string, files: number}}>} rows - Exact canon or family binding identities to replace.
+ * @returns {string} Updated profile YAML; the input is returned unchanged when no rows are supplied.
+ */
+export function renderCanonBindingChanges(original, rows) {
+  if (typeof original !== 'string' || !Array.isArray(rows)) throw new Error('canon binding changes need YAML text and identity rows');
+  const lines = linesOf(original);
+  const entries = lines.map((line, index) => lineEntry(line, index)).filter(Boolean);
+  const root = { start: -1, end: lines.length, indent: -1 };
+  const selected = new Set();
+  for (const row of rows) {
+    if (!KEY.test(row?.profile ?? '') || !supportedBinding(row?.binding) || typeof row?.package !== 'string' || !row.package) throw new Error('canon binding changes need a supported profile, package and binding path');
+    const identity = `${row.profile}.${row.binding}`;
+    if (selected.has(identity)) throw new Error(`${identity}: duplicate binding change`);
+    selected.add(identity);
+    if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(row.to?.version ?? '') || !/^[a-f0-9]{64}$/i.test(row.to?.value ?? '')
+      || !Number.isSafeInteger(row.to?.files) || row.to.files < 1) throw new Error(`${identity}: invalid replacement version or digest`);
+    const { node, at } = bindingNode(entries, root, row);
+    const version = scalar(entries, node, 'version', at);
+    const digest = mapping(entries, node, 'contentDigest', at);
+    const value = scalar(entries, digest, 'value', `${at}.contentDigest`);
+    const files = scalar(entries, digest, 'files', `${at}.contentDigest`);
+    replaceScalar(lines, version, row.to.version);
+    // A hexadecimal digest can contain digits only; quoting preserves its string identity in YAML.
+    replaceScalar(lines, value, `'${row.to.value}'`);
+    replaceScalar(lines, files, row.to.files);
+  }
+  return lines.join('');
+}

package/runtime/scripts/lib/css-rules.mjs

@@ -218,3 +218,21 @@ export function utilityFamilies(utility) {
 export function ruleFamilies(rule) {
   return [...new Set([...rule.apply.flatMap(utilityFamilies), ...rule.declarations.map((entry) => propertyFamily(entry.property)).filter(Boolean)])].sort(byCodeUnit);
 }
+
+// Container composition is layout even when the vendor sets a default for it. Keep this separate from
+// ruleFamilies: the vendor census records every declaration, while the strict judge measures paint.
+const LAYOUT_FAMILIES = new Set([
+  'gap', 'inline-size', 'display', 'order',
+  'flex', 'flex-basis', 'flex-direction', 'flex-flow', 'flex-grow', 'flex-shrink', 'flex-wrap',
+  'align-content', 'align-items', 'align-self',
+  'justify-content', 'justify-items', 'justify-self',
+  'place-content', 'place-items', 'place-self',
+  'grid', 'grid-template', 'grid-template-areas', 'grid-template-columns', 'grid-template-rows',
+  'grid-auto-columns', 'grid-auto-flow', 'grid-auto-rows', 'grid-area',
+  'grid-column', 'grid-column-start', 'grid-column-end', 'grid-row', 'grid-row-start', 'grid-row-end',
+]);
+
+/** The paint families a strict Grammar may only change through a declared vendor override. */
+export function repaintFamilies(rule) {
+  return ruleFamilies(rule).filter((family) => !LAYOUT_FAMILIES.has(family));
+}

package/runtime/scripts/lib/example-refs.mjs

@@ -51,7 +51,7 @@ export const REFERENCE_EXAMPLE_APP = 'full-app';
 
 /** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`); the
  *  runtime's own product maps to the core sheet. */
-export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo' });
+export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo', 'offset-pop': 'offset-pop' });
 
 /** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
 export const PRODUCT_NAME_SEGMENT = /^(nivo|starci|mia)[-\w]*$/i;

package/runtime/scripts/lib/grammar-lint.mjs

@@ -0,0 +1,48 @@
+// Grammar-family lint selection reads the family catalog; an absent selection never chooses a family.
+import fs from 'node:fs';
+import { parseYamlCached } from './yaml-cached.mjs';
+
+const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
+
+function selectedFamily(family) {
+  if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
+  const catalog = parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
+  const matches = (catalog.families ?? []).filter(entry => entry.id === family);
+  if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+  return { catalog, selected: matches[0] };
+}
+
+/** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
+export function grammarFamilyFor(family) {
+  return Object.freeze(selectedFamily(family).selected);
+}
+
+/** The declared family's lint contract, including an explicit null package when that family has no rules. */
+export function grammarLintFor(family) {
+  const { selected } = selectedFamily(family);
+  if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
+    throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+  }
+  const lint = selected.lint;
+  if (lint.package === null) return Object.freeze({ family, package: null });
+  if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
+    || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
+    || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
+    throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
+  }
+  return Object.freeze({ family, package: lint.package, factory: lint.factory, prefix: lint.prefix });
+}
+
+/** The selected family's shared component/export contract, resolved through its catalog reference. */
+export function grammarContractFor(family) {
+  const { catalog, selected } = selectedFamily(family);
+  const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
+  const contract = owners.length === 1 ? owners[0].componentContract : null;
+  if (!contract || typeof contract.package !== 'string' || !contract.package
+    || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
+    || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
+    || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
+    throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
+  }
+  return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
+}