@starci/hfs 4.7.34 → 4.7.35

package/runtime/scripts/lib/grammar-vendor-source.mjs

@@ -0,0 +1,345 @@
+// grammar-vendor-source.mjs - pure JSX and expression readers for Grammar vendor-parity judgments.
+// The caller supplies source text, import aliases and measured role declarations; this module performs no I/O.
+// Kept separate from the parity rules so parsing and vendor render-prop custody have one owner.
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+// ---------------------------------------------------------------------------
+// Reading JSX without a parser: the opening tags of the aliases a file imports from @heroui/react.
+// ---------------------------------------------------------------------------
+
+/** The index after the quoted string that starts at `start`. */
+function skipQuoted(text, start) {
+  const quote = text[start];
+  let index = start + 1;
+  while (index < text.length && text[index] !== quote) index += text[index] === '\\' ? 2 : 1;
+  return index + 1;
+}
+
+/** The index after the template literal that starts at `start`, `${...}` substitutions included. */
+function skipTemplate(text, start) {
+  let index = start + 1;
+  while (index < text.length && text[index] !== '`') {
+    if (text[index] === '\\') index += 2;
+    else if (text[index] === '$' && text[index + 1] === '{') index = skipBraces(text, index + 1);
+    else index += 1;
+  }
+  return index + 1;
+}
+
+/** The index after the balanced `{...}` that starts at `start`. */
+function skipBraces(text, start) {
+  let depth = 0;
+  let index = start;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '"' || char === "'") index = skipQuoted(text, index);
+    else if (char === '`') index = skipTemplate(text, index);
+    else {
+      if (char === '{') depth += 1;
+      if (char === '}') depth -= 1;
+      index += 1;
+      if (depth === 0 && char === '}') return index;
+    }
+  }
+  return index;
+}
+
+/** The index after the value (a string, a template or a braced expression) that starts at `start`. */
+function skipValue(text, start) {
+  const char = text[start];
+  if (char === '"' || char === "'") return skipQuoted(text, start);
+  if (char === '`') return skipTemplate(text, start);
+  return char === '{' ? skipBraces(text, start) : start + 1;
+}
+
+/** Attributes of the opening tag whose name ended at `from`: `{name, raw}` (a spread is named `...`). */
+function readAttributes(text, from) {
+  const attrs = [];
+  let index = from;
+  while (index < text.length) {
+    while (/\s/.test(text[index] ?? '')) index += 1;
+    if (text[index] === '>' || text.startsWith('/>', index)) break;
+    if (text[index] === '{') {
+      const end = skipBraces(text, index);
+      attrs.push({ name: '...', raw: text.slice(index + 1, end - 1) });
+      index = end;
+      continue;
+    }
+    const name = /^[\w:-]+/.exec(text.slice(index, index + 80))?.[0];
+    if (!name) break;
+    index += name.length;
+    if (text[index] !== '=') {
+      attrs.push({ name, raw: 'true' });
+      continue;
+    }
+    index += 1;
+    const end = skipValue(text, index);
+    const raw = text.slice(index, end);
+    attrs.push({ name, raw: raw.startsWith('{') ? raw.slice(1, -1) : raw, offset: raw.startsWith('{') ? index + 1 : index });
+    index = end;
+  }
+  return attrs;
+}
+
+/** The opening tags of the given import aliases: `{alias, part, attrs, line}` (`part` is `Root` for the bare alias). */
+export function heroTags(text, aliases) {
+  if (!aliases.length) return [];
+  const pattern = new RegExp(String.raw`<(${aliases.join('|')})(?:\.(\w+))?(?=[\s/>])`, 'g');
+  return [...text.matchAll(pattern)].map((match) => ({
+    alias: match[1],
+    part: match[2] ?? 'Root',
+    attrs: readAttributes(text, match.index + match[0].length),
+    line: lineOf(text, match.index),
+  }));
+}
+
+/** The vendor imports of a source: alias -> vendor component name. */
+export function importAliases(text) {
+  const aliases = new Map();
+  for (const match of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']@heroui\/react["']/g)) {
+    for (const entry of match[1].split(',').map((part) => part.trim()).filter(Boolean)) {
+      const found = /^(?!type\s)(\w+)(?:\s+as\s+(\w+))?$/.exec(entry);
+      if (found) aliases.set(found[2] ?? found[1], found[1]);
+    }
+  }
+  return aliases;
+}
+
+/** Whether the cursor starts a JavaScript string or template. */
+const isQuoted = (char) => char === '"' || char === "'" || char === '`';
+
+/** Skip strings and comments while looking for JSX rather than text that only resembles it. */
+function skipJsTrivia(text, index) {
+  if (isQuoted(text[index])) return skipValue(text, index);
+  if (text.startsWith('//', index)) {
+    const end = text.indexOf('\n', index);
+    return end < 0 ? text.length : end;
+  }
+  if (text.startsWith('/*', index)) {
+    const end = text.indexOf('*/', index + 2);
+    return end < 0 ? text.length : end + 2;
+  }
+  return undefined;
+}
+
+/** The end of an opening tag, keeping greater-than signs inside attribute expressions intact. */
+function jsxOpeningEnd(text, start) {
+  let index = start;
+  while (index < text.length && text[index] !== '>') {
+    index = /["'{`]/.test(text[index]) ? skipValue(text, index) : index + 1;
+  }
+  return index;
+}
+
+/** Read one opening tag and the cursor after its attributes. */
+function jsxOpening(text, index) {
+  if (text[index] !== '<') return undefined;
+  const opening = /^<([A-Za-z][\w.:-]*)(?=[\s/>])/.exec(text.slice(index));
+  if (!opening) return undefined;
+  const from = index + opening[0].length;
+  const [alias, part = 'Root'] = opening[1].split('.');
+  return { tag: { alias, part, attrs: readAttributes(text, from), index }, end: jsxOpeningEnd(text, from) };
+}
+
+/** Opening JSX tags, excluding JavaScript strings and comments; attribute expressions remain intact. */
+export function jsxTags(text) {
+  const tags = [];
+  let index = 0;
+  while (index < text.length) {
+    const skipped = skipJsTrivia(text, index);
+    if (skipped !== undefined) {
+      index = skipped;
+      continue;
+    }
+    const opening = jsxOpening(text, index);
+    if (!opening) {
+      index += 1;
+      continue;
+    }
+    tags.push(opening.tag);
+    for (const attr of opening.tag.attrs.filter((candidate) => candidate.name !== '...')) {
+      tags.push(...jsxTags(attr.raw).map((tag) => ({ ...tag, index: tag.index + attr.offset })));
+    }
+    index = opening.end + 1;
+  }
+  return tags;
+}
+
+/** Apply the delimiter at a cursor to an expression's nesting depth. */
+const expressionDepth = (depth, char) => {
+  if ('({['.includes(char)) return depth + 1;
+  return ')}]'.includes(char) ? depth - 1 : depth;
+};
+
+/** The top-level operator at this cursor, with nullish and logical operators kept whole. */
+function expressionOperator(raw, index) {
+  const logical = /^(?:\?\?|\|\||&&)/.exec(raw.slice(index));
+  if (logical) return logical[0];
+  if (/\s/.test(raw[index - 1] ?? '') && /^(?:as|satisfies)\s/.test(raw.slice(index))) return 'type';
+  return ['?', ':', ','].includes(raw[index]) ? raw[index] : undefined;
+}
+
+/** Top-level expression operators, excluding strings, nested expressions and nullish `??`. */
+function expressionOperators(raw) {
+  const operators = [];
+  let depth = 0;
+  let index = 0;
+  while (index < raw.length) {
+    const char = raw[index];
+    if (isQuoted(char)) {
+      index = skipValue(raw, index);
+      continue;
+    }
+    depth = expressionDepth(depth, char);
+    const operator = depth === 0 ? expressionOperator(raw, index) : undefined;
+    if (operator !== undefined) operators.push({ operator, index });
+    index += ['??', '||', '&&'].includes(operator) ? 2 : 1;
+  }
+  return operators;
+}
+
+/** The first top-level expression terminator; constant initializers can continue a conditional on the next line. */
+function expressionEnd(text, start, continuedConditional = false) {
+  let depth = 0;
+  let index = start;
+  while (index < text.length) {
+    const char = text[index];
+    if (isQuoted(char)) {
+      index = skipValue(text, index);
+      continue;
+    }
+    depth = expressionDepth(depth, char);
+    if (depth === 0 && char === ';') break;
+    if (depth === 0 && char === '\n') {
+      const continues = continuedConditional && /^\s*(?:\?(?!\.)|:|\|\||&&)/.test(text.slice(index + 1));
+      if (!continues) break;
+    }
+    index += 1;
+  }
+  return index;
+}
+
+/** A local constant initializer, including balanced objects and multiline conditional branches. */
+function constantExpression(text, identifier) {
+  const declaration = new RegExp(String.raw`\bconst\s+${identifier}(?:\s*:\s*[^=;\n]+)?\s*=`).exec(text);
+  if (!declaration) return undefined;
+  const start = declaration.index + declaration[0].length;
+  return text.slice(start, expressionEnd(text, start, true)).trim();
+}
+
+/** The static entries of an object constant used as a role lookup table. */
+function expressionEntries(raw) {
+  raw = raw.trim();
+  const assertion = expressionOperators(raw).find((entry) => entry.operator === 'type');
+  if (assertion) raw = raw.slice(0, assertion.index).trim();
+  if (!raw.startsWith('{') || !raw.endsWith('}')) return [];
+  const body = raw.slice(1, -1);
+  const separators = expressionOperators(body).filter((entry) => entry.operator === ',').map((entry) => entry.index);
+  const entries = [];
+  let start = 0;
+  for (const end of [...separators, body.length]) {
+    const entry = body.slice(start, end).trim();
+    const colon = expressionOperators(entry).find((operator) => operator.operator === ':');
+    if (colon) entries.push({ key: entry.slice(0, colon.index).trim().replace(/^['"]|['"]$/g, ''), value: entry.slice(colon.index + 1) });
+    start = end + 1;
+  }
+  return entries;
+}
+
+/** Whether one balanced pair encloses the complete expression rather than only its first operand. */
+function enclosesExpression(raw) {
+  if (!raw.startsWith('(') || !raw.endsWith(')')) return false;
+  let depth = 0;
+  let index = 0;
+  while (index < raw.length) {
+    const char = raw[index];
+    if (isQuoted(char)) {
+      index = skipValue(raw, index);
+      continue;
+    }
+    if (char === '(') depth += 1;
+    if (char === ')') depth -= 1;
+    if (depth === 0) return index === raw.length - 1;
+    index += 1;
+  }
+  return false;
+}
+
+/** Match a conditional's colon without confusing nested conditionals with its own branches. */
+function conditionalColon(operators, question) {
+  let nested = 0;
+  return operators.slice(question + 1).find((entry) => {
+    if (entry.operator === '?') nested += 1;
+    if (entry.operator !== ':') return false;
+    if (nested > 0) {
+      nested -= 1;
+      return false;
+    }
+    return true;
+  });
+}
+
+/** Resolve a role lookup through a local object constant, considering every possible computed key. */
+function memberExpressionStrings(text, member, seen) {
+  if (seen.has(member[1])) return [];
+  const initializer = constantExpression(text, member[1]);
+  if (!initializer) return [];
+  seen.add(member[1]);
+  const literalKey = member[3] ?? (/^(['"])([^'"]+)\1$/.exec(member[2]?.trim() ?? '')?.[2]);
+  return expressionEntries(initializer).filter((entry) => literalKey === undefined || entry.key === literalKey).flatMap((entry) => expressionStrings(text, entry.value, new Set(seen)));
+}
+
+/** Result literals of a JSX expression, including local constants; condition literals are not result values. */
+export function expressionStrings(text, raw, seen = new Set()) {
+  raw = raw.trim();
+  if (enclosesExpression(raw)) return expressionStrings(text, raw.slice(1, -1), seen);
+  if (/^(?:"[^"\n]*"|'[^'\n]*'|`[^`$]*`)$/.test(raw)) return [raw.slice(1, -1)];
+  const operators = expressionOperators(raw);
+  const assertion = operators.find((entry) => entry.operator === 'type');
+  if (assertion) return expressionStrings(text, raw.slice(0, assertion.index), seen);
+  const question = operators.findIndex((entry) => entry.operator === '?');
+  const colon = question >= 0 ? conditionalColon(operators, question) : undefined;
+  if (colon) return [...expressionStrings(text, raw.slice(operators[question].index + 1, colon.index), new Set(seen)), ...expressionStrings(text, raw.slice(colon.index + 1), new Set(seen))];
+  const logical = operators.find((entry) => ['??', '||', '&&'].includes(entry.operator));
+  if (logical) return [...expressionStrings(text, raw.slice(0, logical.index), new Set(seen)), ...expressionStrings(text, raw.slice(logical.index + 2), new Set(seen))];
+  const member = /^([A-Za-z_$][\w$]*)(?:\[([\s\S]+)\]|\.([A-Za-z_$][\w$]*))$/.exec(raw);
+  if (member) return memberExpressionStrings(text, member, seen);
+  const identifier = /^([A-Za-z_$][\w$]*)$/.exec(raw)?.[1];
+  if (!identifier || seen.has(identifier)) return [];
+  seen.add(identifier);
+  const initializer = constantExpression(text, identifier);
+  return initializer ? expressionStrings(text, initializer, seen) : [];
+}
+
+/** The first callback parameter, after optional parentheses and surrounding whitespace. */
+function callbackParameter(source) {
+  const trimmed = source.trimStart();
+  const parameter = trimmed.startsWith('(') ? trimmed.slice(1).trimStart() : trimmed;
+  return /^([A-Za-z_$][\w$]*)/.exec(parameter)?.[1];
+}
+
+/** A render callback's source offset, resolving a named local callback when present. */
+function callbackStart(text, callback) {
+  if (!/^[\w$]+$/.test(callback.raw)) return callback.offset;
+  const declaration = new RegExp(String.raw`\bconst\s+${callback.raw}\s*=`).exec(text);
+  return declaration ? declaration.index + declaration[0].length : undefined;
+}
+
+/** The native root receiving the vendor's render props and the role contracts it therefore inherits. */
+function vendorRenderRoot(text, callback, declarations) {
+  const start = callbackStart(text, callback);
+  if (start === undefined) return [];
+  const parameter = callbackParameter(text.slice(start));
+  if (!parameter) return [];
+  const root = jsxTags(text.slice(start, expressionEnd(text, start)))[0];
+  if (!root || !root.attrs.some((attr) => attr.name === '...' && attr.raw.trim() === `...${parameter}`)) return [];
+  const roles = Object.entries(declarations).filter(([, entry]) => entry.contracts?.includes(`${callback.owner}.Root`)).map(([role]) => role);
+  return [{ index: root.index + start, roles }];
+}
+
+/** The local render callbacks supplied to vendor roots keep the vendor's state, semantics and prop custody. */
+export function vendorRenderRoots(text, aliases, declarations) {
+  const callbacks = heroTags(text, [...aliases.keys()]).flatMap((tag) => tag.attrs.filter((attr) => attr.name === 'render').map((attr) => ({ raw: attr.raw.trim(), offset: attr.offset, owner: aliases.get(tag.alias) })));
+  return callbacks.flatMap((callback) => vendorRenderRoot(text, callback, declarations));
+}

package/runtime/scripts/lib/numeric-match.mjs

@@ -0,0 +1,5 @@
+/** Read the first numeric capture of a matching recognizer; unmatched values have no number. */
+export function numericMatch(value, pattern) {
+  const match = pattern.exec(String(value ?? ''));
+  return match ? Number(match[1]) : null;
+}

package/runtime/scripts/lib/source-package-imports.mjs

@@ -0,0 +1,111 @@
+// Source-package imports preserve published export and exact dependency contracts without a workspace install.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire, registerHooks } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { insidePath, pathKey, realPath } from './path-key.mjs';
+
+const packageNameOf = (specifier) => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
+
+function conditionalTarget(value, conditions) {
+  if (typeof value === 'string' || value === null) return value;
+  if (Array.isArray(value)) return value.map(entry => conditionalTarget(entry, conditions)).find(entry => entry !== undefined);
+  if (!value || typeof value !== 'object') return undefined;
+  for (const [condition, target] of Object.entries(value)) {
+    if (condition === 'default' || conditions.includes(condition)) {
+      const selected = conditionalTarget(target, conditions);
+      if (selected !== undefined) return selected;
+    }
+  }
+}
+
+/** Resolve only exports that the package publishes; private paths remain unavailable in a source checkout. */
+function exportedTarget(exports, subpath, conditions) {
+  if (!exports || typeof exports !== 'object' || Array.isArray(exports)) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
+  const keys = Object.keys(exports);
+  if (keys.every(key => !key.startsWith('.'))) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
+  if (Object.hasOwn(exports, subpath)) return conditionalTarget(exports[subpath], conditions);
+  const patterns = keys.filter(key => key.includes('*')).sort((a, b) => b.indexOf('*') - a.indexOf('*') || b.length - a.length);
+  for (const pattern of patterns) {
+    const [prefix, suffix] = pattern.split('*');
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
+    const match = subpath.slice(prefix.length, suffix ? -suffix.length : undefined);
+    const target = conditionalTarget(exports[pattern], conditions);
+    return typeof target === 'string' ? target.replaceAll('*', match) : target;
+  }
+}
+
+function sourcePackages(root, packages) {
+  return Object.entries(packages).filter(([, pin]) => typeof pin?.source === 'string').map(([name, pin]) => {
+    const manifestFile = realPath(path.resolve(root, pin.source));
+    if (!insidePath(root, manifestFile, { key: pathKey })) throw new Error(`Source package ${name} is outside the source tree`);
+    return { name, pin, manifestFile, root: path.dirname(manifestFile), manifest: null };
+  }).sort((a, b) => b.root.length - a.root.length);
+}
+
+function manifestOf(source) {
+  source.manifest ??= JSON.parse(fs.readFileSync(source.manifestFile, 'utf8'));
+  if (source.manifest.name !== source.name || source.manifest.version !== source.pin.version) {
+    throw new Error(`Source package ${source.name} does not match its pinned name and version`);
+  }
+  return source.manifest;
+}
+
+/** Settle each declared bare dependency before installing a hook, using the consumer first and source install second. */
+function consumerDependencyTargets(sources, consumerRoot) {
+  const consumer = createRequire(path.join(consumerRoot, 'package.json'));
+  for (const source of sources) {
+    const manifest = manifestOf(source), local = createRequire(source.manifestFile);
+    source.consumerDependencies = new Map();
+    for (const name of Object.keys({ ...manifest.peerDependencies, ...manifest.optionalDependencies, ...manifest.dependencies })) {
+      for (const require of [consumer, local]) {
+        try { source.consumerDependencies.set(name, pathToFileURL(require.resolve(name)).href); break; }
+        catch { /* The next install may carry the dependency; a missing import still fails through the native resolver. */ }
+      }
+    }
+  }
+}
+
+function resolveSource(specifier, context, nextResolve, sources, consumerRoot) {
+  if (!context.parentURL?.startsWith('file:')) return nextResolve(specifier, context);
+  const parent = fileURLToPath(context.parentURL);
+  const owner = sources.find(source => insidePath(source.root, parent, { key: pathKey }));
+  const target = sources.find(source => source.name === packageNameOf(specifier));
+  if (!target) {
+    const dependency = owner?.consumerDependencies?.get(specifier);
+    return dependency ? { url: dependency, shortCircuit: true } : nextResolve(specifier, context);
+  }
+  if (!owner && (!consumerRoot || !insidePath(consumerRoot, parent, { key: pathKey }))) return nextResolve(specifier, context);
+  const manifest = manifestOf(target);
+  if (owner) {
+    const caller = manifestOf(owner);
+    const dependency = caller.dependencies?.[target.name] ?? caller.devDependencies?.[target.name] ?? caller.optionalDependencies?.[target.name];
+    if (owner !== target && dependency !== manifest.version) throw new Error(`${owner.name} must declare its source dependency ${target.name}@${manifest.version} exactly`);
+  }
+  const subpath = `.${specifier.slice(target.name.length)}`;
+  const published = exportedTarget(manifest.exports, subpath, context.conditions);
+  if (typeof published !== 'string' || !published.startsWith('./')) throw new Error(`${specifier} is not a published source-package export`);
+  const resolved = path.resolve(target.root, published);
+  if (!insidePath(target.root, resolved, { key: pathKey }) || published.split('/').includes('node_modules')) throw new Error(`${specifier} has an invalid source-package export target`);
+  return { url: pathToFileURL(resolved).href, shortCircuit: true };
+}
+
+/**
+ * Await source imports with pinned local packages resolved through their own public exports.
+ * Imports originating inside a declared source package obey exact dependency versions and public exports.
+ * An explicit consumerRoot also redirects that consumer's selected source-package imports and resolves source
+ * packages' declared bare imports and requires from the consumer install first. This keeps a parser and its
+ * typed rules on the same dependency instances. The hook is removed on success or failure; callers await
+ * every import and dependent action. Normal installed-package resolution remains in force afterward.
+ * @param {{ root: string, packages: Record<string, { version: string, source?: string }>, consumerRoot?: string }} input - Canonical source pins and an optional bounded consumer source root.
+ * @param {() => Promise<unknown>} action - Imports whose package contracts are being checked.
+ * @returns {Promise<unknown>} The action's result, without a persistent resolver change.
+ */
+export async function withSourcePackageImports({ root, packages, consumerRoot }, action) {
+  const sources = sourcePackages(realPath(root), packages);
+  const consumer = consumerRoot === undefined ? null : realPath(consumerRoot);
+  if (consumer) consumerDependencyTargets(sources, consumer);
+  const hook = registerHooks({ resolve: (specifier, context, nextResolve) => resolveSource(specifier, context, nextResolve, sources, consumer) });
+  try { return await action(); }
+  finally { hook.deregister(); }
+}

package/runtime/scripts/work/draw/draw-layer.mjs

@@ -2,7 +2,7 @@
 // "this is KNOWLEDGE, not golden rules" - the runtime catches these from knowledge and gates, never from owner feedback).
 //
 //   DRAW_NESTED_VARIANT    knowledge/ui/proof/anatomy-source.yaml ANATOMY-2. The layer chain is page Background ->
-//                          Surface -> nested control: every form control ON a surface (a SurfaceCard of any frame, a
+//                          Surface -> nested control: every form control ON a painted surface (a SurfaceCard, a
 //                          card, a dialog / drawer panel) carries HeroUI's nested `secondary` variant - the choice
 //                          controls (Checkbox, RadioGroup, ...) as much as the text fields (case-1); a form region
 //                          (fields plus a primary submit) stands in a Surface, never directly on the Background
@@ -39,9 +39,9 @@ const VARIANT_CONTROLS = Object.freeze(['Input', 'Textarea', 'Select', 'ComboBox
 /** Every grammar field control (the variant ones plus those without a vendor variant): what makes a region a form. */
 const FIELD_CONTROLS = Object.freeze([...VARIANT_CONTROLS, 'Switch', 'Slider', 'FileDropzone']);
 /** Components that paint a surface of their own. */
-const SURFACE_COMPONENTS = Object.freeze(['SurfaceCard', 'SurfaceListCard', 'SurfaceAccordionCard', 'Rail', 'Sidebar', 'Dialog', 'Drawer', 'AlertDialog', 'Popover']);
+const SURFACE_COMPONENTS = Object.freeze(['SurfaceCard', 'SurfaceListCard', 'Sidebar', 'Dialog', 'Drawer', 'AlertDialog', 'Popover']);
 /** Boolean surface-owner hooks emitted by Grammar compositions. */
-const SURFACE_STAMPS = Object.freeze(['data-grammar-surface', 'data-grammar-surface-card', 'data-grammar-surface-list', 'data-grammar-surface-accordion-card', 'data-grammar-rail']);
+const SURFACE_STAMPS = Object.freeze(['data-grammar-surface', 'data-grammar-surface-card', 'data-grammar-surface-list', 'data-grammar-surface-accordion-card']);
 /** The vendor class prefixes that carry the layer variant (`<prefix>--primary|secondary`). */
 const VARIANT_CLASS_PREFIXES = Object.freeze(['input', 'input-group', 'textfield', 'textarea', 'select', 'combo-box', 'search-field', 'number-field',
   'date-input-group', 'date-field', 'time-field', 'date-picker', 'checkbox', 'checkbox-group', 'radio-group', 'input-otp']);
@@ -49,8 +49,9 @@ const VARIANT_CLASS_PREFIXES = Object.freeze(['input', 'input-group', 'textfield
 const VARIANT_CLASS = new RegExp(`^(?:${VARIANT_CLASS_PREFIXES.join('|')})--(primary|secondary)$`);
 const componentOf = (attrs) => attrs?.['data-component'] ?? attrs?.['data-grammar-component'] ?? null;
 
-/** Whether one parsed/DOM element establishes a surface nesting boundary, including frameless compositions. */
+/** Whether one parsed/DOM element paints a surface; unpainted layout containers inherit their parent. */
 function isSurface({ component, attrs, classes }) {
+  if (attrs['data-grammar-frame'] === 'frameless') return false;
   if (SURFACE_COMPONENTS.includes(component)) return true;
   if (attrs['data-grammar-nesting'] === 'surface') return true;
   if (SURFACE_STAMPS.some((stamp) => attrs[stamp] === 'true')) return true;

package/scaffold/app.mjs

@@ -33,6 +33,7 @@ import { init as gitInit } from '../runtime/scripts/api/git/init.mjs';
 import { insidePath, samePath } from '../runtime/scripts/lib/path-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { sonarGateName } from '../sync/sonar-key.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 const NAME = /^[a-z][a-z0-9-]*$/;
 const APP_DIR = '__app__';
@@ -126,7 +127,7 @@ export const packageJsonText = value => `${JSON.stringify(value, null, 2)}\n`;
 const STARTER_SIDES = Object.freeze({
   be: Object.freeze({ apps: [{ name: 'core', kind: 'api' }, { name: 'cli', kind: 'cli' }], kinds: ['api', 'cli'], connections: [{ name: 'primary', envPrefix: 'PRIMARY_DB', owner: 'core', isolation: 'database' }] }),
   // fe: the landing and the product app, over the shared ui and i18n packages (both opt-in slots, enabled here).
-  fe: Object.freeze({ apps: [{ name: 'landing', kind: 'next' }, { name: 'app', kind: 'next' }], reads: ['be/contracts/'], optionalSlots: ['fe.package.ui', 'fe.package.i18n'] }),
+  fe: Object.freeze({ grammar: 'starci', apps: [{ name: 'landing', kind: 'next' }, { name: 'app', kind: 'next' }], reads: ['be/contracts/'], optionalSlots: ['fe.package.ui', 'fe.package.i18n'] }),
 });
 
 /** The lite starter is the upgrade-safe subset: one API, one web app and one Supabase schema authority. */
@@ -137,7 +138,7 @@ const LITE_STARTER_SIDES = Object.freeze({
     connections: [{ name: 'primary', envPrefix: 'PRIMARY_DB', owner: 'api', isolation: 'schema', provider: 'supabase' }],
     reads: ['supabase/types/'],
   }),
-  fe: Object.freeze({ apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/', 'supabase/types/'] }),
+  fe: Object.freeze({ grammar: 'starci', apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/', 'supabase/types/'] }),
 });
 
 /** The checked local Supabase auth posture of every newly scaffolded lite app. */
@@ -313,9 +314,10 @@ const ROOT_OVERRIDES = Object.freeze(['@graphql-tools/utils', '@xyflow/react', '
  * The root package.json of a new app, the monorepo root: name, workspaces, npm, its edition's dependencies with their runtime
  * peers, the fe stack's root tools and the one-version overrides, at canon pins.
  */
-function packageManifest(name, pins, edition, stack = coreFeStackPackages()) {
+function packageManifest(name, pins, edition, grammar, stack = coreFeStackPackages()) {
   const dependencies = edition === 'lite' ? LITE_STARTER_DEPENDENCIES : STARTER_DEPENDENCIES;
-  const devDependencies = { ...dependencies.devDependencies, ...Object.fromEntries(stack.root.map(dependency => [dependency, null])) };
+  const grammarLint = grammarLintFor(grammar);
+  const devDependencies = { ...dependencies.devDependencies, ...Object.fromEntries(stack.root.map(dependency => [dependency, null])), ...(grammarLint.package ? { [grammarLint.package]: null } : {}) };
   const pkg = { name, version: '0.0.0', private: true, packageManager: PACKAGE_MANAGER, workspaces: [...WORKSPACES], dependencies: pinnedSection(dependencies.dependencies, pins), devDependencies: pinnedSection(devDependencies, pins) };
   pkg.dependencies = pinnedSection({ ...pkg.dependencies, ...peerDependencies(pkg, pins) }, pins);
   pkg.overrides = pinnedSection(Object.fromEntries(ROOT_OVERRIDES.map(dependency => [dependency, null])), pins);
@@ -667,7 +669,7 @@ export function scaffoldApp({ name, into, presets, edition = 'full', authCallbac
   const declaration = starterDeclaration(name, manifest, edition);
   if (authCallback) enableAuthCallback(declaration);
   const app = resolveRepoDeclaration(manifest, declaration);
-  const pkg = packageManifest(name, pins, app.edition);
+  const pkg = packageManifest(name, pins, app.edition, app.sides.fe.grammar);
   const timestamp = now().toISOString().replace(/\D/g, '').slice(0, 14);
   const files = [
     { path: 'hfs.json', content: jsonText(declaration) },

package/src/main.mjs

@@ -10,6 +10,8 @@
 //                                            --fast, and a repository without prettier is a refusal); soft-size backlog (report only); then the whole
 //                                            architecture machine (tiers, owners, clones, dead exports, module registration, the
 //                                            front-end and back-end source rules), each violation a finding with its why.
+//                                            ESLint executes once per side through the installed managed config; the FE config composes
+//                                            the universal canon and the explicitly selected Grammar-family canon.
 //                                            --fast: only what changed since the merge-base with origin/main (else main; --base
 //                                            overrides it); the machine
 //                                            runs on those owners without clones and dead exports. No merge-base is a refusal
@@ -60,7 +62,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isMain } from '../runtime/scripts/lib/is-main.mjs';
-import { checkDatabase, checkRepository, explainPath, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
+import { changedSince, checkDatabase, checkRepository, explainPath, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
 import { secretMain } from '../runtime/scripts/hfs/secret.mjs';
 import { dbBaselineMain } from '../runtime/scripts/hfs/db-baseline-verb.mjs';
 import { dbRestampMain } from '../runtime/scripts/hfs/db-restamp-verb.mjs';
@@ -79,7 +81,7 @@ import { addKind } from '../scaffold/add.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
 import { contractEmitFindings } from '../runtime/scripts/hfs/rules/contract.mjs';
-import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { eslintRepository, lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
 import { writeReport } from '../report/sonar.mjs';
 import { checkEdition } from '../upgrade/check.mjs';
 import { UpgradeError, upgradeMain } from '../upgrade/index.mjs';
@@ -187,11 +189,17 @@ function printCheckOverview(result, out) {
   if (result.fast) out(`  ${result.fast.changed} path${result.fast.changed === 1 ? '' : 's'} changed since ${result.fast.base.slice(0, 12)}\n`);
   out(`  architecture machine: ${machineDescription(result.machine)}\n`);
   if (result.contracts) out(`  contract snapshots: ${contractDescription(result.contracts)}\n`);
+  if (result.eslint) {
+    const sides = Object.entries(result.eslint.sides).map(([side, run]) => `${side}: ${run.files} files${run.skipped ? ` (${run.skipped})` : ''}`).join(', ');
+    out(`  ESLint: ${sides}\n`);
+    for (const error of result.eslint.errors) out(`  ESLint tool error: ${error}\n`);
+  }
 }
 
 function printFindingGroup(code, list, out) {
   const first = list[0];
-  out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
+  if (first.engine === 'eslint') out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}\n`);
+  else out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
   for (const finding of list.slice(0, PER_CODE_LIMIT)) out(`  - ${finding.message}\n`);
   if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
 }
@@ -264,7 +272,7 @@ export function appRootAbove(dir) {
 }
 
 /** `starci app lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { cwd, stdout, presets, prettier }) {
+async function lintMain(argv, { cwd, stdout, presets, prettier, runLinter, checkApp = runCheck }) {
   const opts = parseLintArgs(argv);
   // --workspace names a folder from the working directory (`starci app lint --workspace .` is an fe workspace script); the app
   // root is then the nearest folder above it that holds hfs.json, and the workspace is passed on app-relative.
@@ -272,8 +280,8 @@ async function lintMain(argv, { cwd, stdout, presets, prettier }) {
   const repoRoot = path.resolve(workspaceDir ? appRootAbove(workspaceDir) : cwd);
   if (workspaceDir) opts.workspace = path.relative(repoRoot, workspaceDir).split(path.sep).join('/');
   const { report, sonar, exit } = await lintRepository({
-    repoRoot, opts, trackedFiles,
-    hfsCheck: (root) => runCheck({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
+    repoRoot, opts, trackedFiles, runLinter,
+    hfsCheck: (root) => checkApp({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
   });
   if (opts.sonar !== undefined) writeReport(path.resolve(cwd, opts.sonar), sonar);
   if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
@@ -336,14 +344,19 @@ function printCheckProofs(result, out) {
   if (result.coverage) out(formatCoverageReport(result.coverage));
 }
 
-async function checkMain(opts, { cwd: repoRoot, edition, stdout: out, presets, prettier }) {
+async function checkMain(opts, { cwd: repoRoot, edition, stdout: out, presets, prettier, checkApp = runCheck, runLinter }) {
   if (opts.positional.length) throw new Error('starci app check takes no path');
   if (opts.base !== undefined && opts.fast !== true) throw new Error('--base names the ref --fast compares with; it needs --fast');
-  const checked = await checkEdition({ repoRoot, edition, normal: () => runCheck({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
-  const result = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: opts['coverage-from'] });
+  const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
+  const proof = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: opts['coverage-from'] });
+  const changed = opts.fast === true ? changedSince(repoRoot, proof.fast?.base ?? opts.base).files : null;
+  const existing = changed ? changed.filter(file => fs.existsSync(path.join(repoRoot, file))) : [];
+  const eslint = await eslintRepository({ repoRoot, changed, existing, run: runLinter });
+  const findings = [...proof.findings, ...eslint.findings.map(finding => ({ ...finding, code: finding.code ?? finding.rule, level: 'error' }))];
+  const result = { ...proof, findings, counts: { ...proof.counts, error: proof.counts.error + eslint.findings.length }, eslint: { ...eslint.engine, errors: eslint.errors }, ok: proof.ok && eslint.findings.length === 0 && eslint.errors.length === 0 };
   if (opts.json) out(`${JSON.stringify(result, null, 2)}\n`);
   else { printCheck(result, out); printCheckProofs(result, out); }
-  return result.ok ? 0 : 1;
+  return eslint.errors.length ? 2 : result.ok ? 0 : 1;
 }
 
 function emitMain(opts, { cwd: repoRoot, stdout: out, run }) {
@@ -434,10 +447,10 @@ function errorMessage(error) {
   return `starci app: ${error.message}\n${USAGE}`;
 }
 
-/** `run` injects the Supabase command runner and `stackIo` the spawn, fetch, sleep and clock seams of the Swarm tooling; IO and tool seams keep every verb independently testable. */
+/** `run` injects the Supabase runner, `runLinter` the linter transport, `checkApp` the HFS check and `stackIo` Swarm tools; production defaults execute every check. */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
-  env = process.env, stdin, sops, tools, platform, stackIo,
+  env = process.env, stdin, sops, tools, platform, stackIo, runLinter, checkApp,
 } = {}) {
   try {
     const global = globalOptions(argv, path.resolve(baseCwd));
@@ -445,7 +458,7 @@ export async function main(argv, {
     const out = global.quiet ? () => {} : stdout;
     if (global.help) { out(USAGE); return 0; }
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
-    return await dispatchMain(verb, rest, { cwd: global.cwd, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo });
+    return await dispatchMain(verb, rest, { cwd: global.cwd, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
   } catch (error) {
     stderr(errorMessage(error));
     return 2;