@starci/eslint-grammar-core 0.16.0 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.16.2 - 2026-10-31
+
+- Changed: the peer moves to eslint-canon-fe 9.6.2; the bundled canon pins name @starci/grammar 0.16.2 (the horizontal Stepper connector line; SurfaceListCard takes its depth from the surface context).
+- Added: starci-grammar/no-raised-surface-in-surface (R340, FE_RAISED_SURFACE_IN_SURFACE): a depth="top" forced on a SurfaceListCard that a SurfaceCard, SurfaceListCard or SurfaceAccordionCard of the same file encloses is a finding (BOUNDARY-6, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); the Grammar resolves a nested surface's depth from the surface context. Specs: src/surface-depth.spec.ts.
+
+## 0.16.1 - 2026-10-30
+
+- Changed: the peer moves to eslint-canon-fe 9.6.1; the bundled canon pins name @starci/grammar 0.16.1 (accentCorner, Backdrop, the shell filling the viewport).
+
 ## 0.16.0 - 2026-10-30
 
 - Changed: the peer moves to eslint-canon-fe 9.6.0; the bundled runtime copies are now generated from the hfs build (TypeScript emitted as .mjs) per runtime/bundle.json, with a drift check in CI; the copies the package keeps as its own are listed there and stay hand-maintained; the bundled canon pins name hfs 4.12.0, eslint-canon-be 3.9.0, eslint-canon-fe 9.6.0, the Grammar family 0.16.0, jest-preset 2.5.3 and test-world 1.3.3. No rule of this package changed.

package/README.md

@@ -19,7 +19,7 @@ Family helpers and the generated runtime closure belong to this package.
 
 The rule IDs remain stable when their namespace moves. Laws cover the fixed app shell and navbar,
 Grammar-owned structural elements, glyphs and icon sizes, destructive menu entries, status inks,
-chip labels that start uppercase, generated art rendered through `Mascot` or `MediaFrame` with every `Mascot` naming its asset slot, the page head composed by `PageHeader`, the route page as one `Page` with its tabs in the header, heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
+chip labels that start uppercase, generated art rendered through `Mascot` or `MediaFrame` with every `Mascot` naming its asset slot, the page head composed by `PageHeader`, the route page as one `Page` with its tabs in the header, heading and token scales, vendor ownership and slot-status composition, and a surface nested in another surface left subordinate (no forced `depth="top"`). Each rule's metadata cites
 its behavioral knowledge source and the governing ownership test. The R318 surface composition
 rules (nested control variants, panel-list alignment, layout-only CSS) stay in the universal canon.
 

package/dist/index.js

@@ -10,6 +10,7 @@ import { rules as menuEntriesRules } from "./menu-entries.js";
 import { rules as pageRules } from "./page.js";
 import { rules as pageHeaderRules } from "./page-header.js";
 import { rules as statusColorsRules } from "./status-colors.js";
+import { rules as surfaceDepthRules } from "./surface-depth.js";
 import { rules as tokensRules } from "./tokens.js";
 import { rules as typographyRules } from "./typography.js";
 import { rules as vendorRules } from "./vendor-boundary.js";
@@ -25,6 +26,7 @@ const CONTRIBUTIONS = [
     { law: "page", rules: pageRules },
     { law: "page-header", rules: pageHeaderRules },
     { law: "status-colors", rules: statusColorsRules },
+    { law: "surface-depth", rules: surfaceDepthRules },
     { law: "tokens", rules: tokensRules },
     { law: "typography", rules: typographyRules },
     { law: "vendor-boundary", rules: vendorRules },

package/dist/lib/why.js

@@ -54,6 +54,11 @@ export const why = {
         en: "The page or layout owner `<file>` draws something beside its Page, a Page inside another (or inside the Page its tabbed segment's layout draws), a bare PageHeader or PageContainer, or no Page at all (itself, through its pure half, or through the one connected block it renders as its root).",
         fix: "Draw one Page: the band as its header, everything else in its body, the measure as its measure. When client data builds the header, render as the root the one connected block that draws the Page and pass the body as its children. Under a segment layout whose Page carries header.tabs, a page draws its body only; that layout's Page has nothing beside it, its head in its header. A page mounted only under the (auth) route group is framed by that group's layout.",
     },
+    "no-raised-surface-in-surface": {
+        code: "FE_RAISED_SURFACE_IN_SURFACE",
+        en: "A Grammar surface in `<file>` forces `depth=\"top\"` inside another surface, raising a surface inside a surface (BOUNDARY-6).",
+        fix: "Drop `depth`: a nested surface is subordinate (outlined, BOUNDARY-5) and the Grammar resolves it from the surface context.",
+    },
     "no-shell-bottom-tabs": {
         code: "FE_APP_SHELL_BOTTOM_TABS",
         en: "Bottom tab navigation replaces the required mobile sidebar drawer.",

package/dist/surface-depth.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "eslint";
+/** A surface inside another surface never forces `depth="top"`: it is subordinate, and the Grammar resolves it. */
+export declare const noRaisedSurfaceInSurface: Rule.RuleModule;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/** Every rule of this law is an error. */
+export declare const recommended: Record<string, "error">;

package/dist/surface-depth.js

@@ -0,0 +1,92 @@
+import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs";
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * The surface depth law (HFS R340 `FE_RAISED_SURFACE_IN_SURFACE`; Grammar BOUNDARY-5 and BOUNDARY-6, DNA
+ * `DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE`): a surface inside another surface is subordinate (outlined, BOUNDARY-5), never
+ * raised (BOUNDARY-6) again.
+ *
+ * Grammar's bounded surfaces read their depth from the surface context (`useSurfaceNesting`): `SurfaceCard`,
+ * `SurfaceAccordionCard` and `SurfaceListCard` draw outlined inside another surface and raised only at the top.
+ * `SurfaceListCard` alone also takes a `depth` prop that overrides the context, so `depth="top"` on a list that sits inside
+ * another surface raises a surface inside a surface.
+ *
+ * WHAT IT READS. A `depth` attribute whose value is the string `"top"` (a literal, or an expression container holding one)
+ * on a depth-accepting surface element (`SurfaceListCard` or `<ns>.SurfaceListCard`), when a `SurfaceCard`,
+ * `SurfaceListCard` or `SurfaceAccordionCard` element of the same file encloses it. A depth computed at run time is not
+ * judged, and neither is a surface nobody encloses in this file (its parent may nest it; Grammar resolves that).
+ *
+ * WHERE IT APPLIES. Product source (`isProductSource`).
+ */
+/** The bounded surfaces that open a surface context for what they enclose. */
+const SURFACES = new Set(["SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard"]);
+/** The surfaces that accept a `depth` prop overriding the one read from context. */
+const DEPTH_PROP = new Set(["SurfaceListCard"]);
+/** The element name of a JSX name: `SurfaceCard`, or `G.SurfaceCard` as `SurfaceCard`. */
+const nameOf = (name) => {
+    if (name.type === "JSXIdentifier")
+        return name.name;
+    if (name.type === "JSXMemberExpression")
+        return name.property.name;
+    return null;
+};
+/** True when a bounded surface element encloses the element the opening tag belongs to. */
+const insideSurface = (opening) => {
+    // The opening tag's parent is the element itself, so the walk starts above that; the Program's parent is null at run time
+    // though the tree's types say a node always has one.
+    for (let current = opening.parent?.parent; current !== undefined && current !== null; current = current.parent) {
+        if (current.type !== "JSXElement")
+            continue;
+        const name = nameOf(current.openingElement.name);
+        if (name !== null && SURFACES.has(name))
+            return true;
+    }
+    return false;
+};
+/** True when an attribute value is statically the string `"top"`. */
+const isTop = (value) => {
+    if (value === null)
+        return false;
+    if (value.type === "Literal")
+        return value.value === "top";
+    if (value.type !== "JSXExpressionContainer")
+        return false;
+    const expression = value.expression;
+    if (expression.type === "Literal")
+        return expression.value === "top";
+    return expression.type === "TemplateLiteral" && expression.expressions.length === 0 && expression.quasis.length === 1 && expression.quasis[0]?.value.cooked === "top";
+};
+/** A surface inside another surface never forces `depth="top"`: it is subordinate, and the Grammar resolves it. */
+export const noRaisedSurfaceInSurface = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R340: a Grammar surface nested in another surface does not force depth=\"top\" (BOUNDARY-6); a nested surface is subordinate (BOUNDARY-5)." },
+        schema: [],
+        messages: {
+            raised: "`<{{element}} depth=\"top\">` is nested inside another Grammar surface, so it raises a surface inside a surface (BOUNDARY-6, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE): a nested surface is subordinate (outlined, BOUNDARY-5). Drop `depth` and let the Grammar resolve it from the surface context.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        return {
+            JSXAttribute(attribute) {
+                if (attribute.name.type !== "JSXIdentifier" || attribute.name.name !== "depth" || !isTop(attribute.value))
+                    return;
+                const opening = attribute.parent;
+                if (opening.type !== "JSXOpeningElement")
+                    return;
+                const element = nameOf(opening.name);
+                if (element === null || !DEPTH_PROP.has(element) || !insideSurface(opening))
+                    return;
+                context.report({ node: attribute, messageId: "raised", data: { element } });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-raised-surface-in-surface": noRaisedSurfaceInSurface,
+};
+defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R340");
+/** Every rule of this law is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));

package/docs/surface-depth.md

@@ -0,0 +1,40 @@
+# A nested surface stays subordinate
+
+Law module: `surface-depth.ts`. Catalogue: R340 FE_RAISED_SURFACE_IN_SURFACE.
+
+Grammar's bounded surfaces (`SurfaceCard`, `SurfaceAccordionCard`, `SurfaceListCard`) read their depth from the surface
+context: raised at the top of a page (BOUNDARY-6), outlined inside another surface (BOUNDARY-5), so two raised surfaces never
+stack (`DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE`). `SurfaceListCard` also takes a `depth` prop that overrides the context;
+forcing `depth="top"` on a list that sits inside another surface raises a surface inside a surface.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline. It applies to product
+source (the route, feature, component, hook, foundation, module and transport tiers and the workspace packages); a script or
+a file no slot owns is not judged.
+
+## `starci-grammar/no-raised-surface-in-surface`
+
+A `depth` attribute whose value is statically the string `"top"` (a literal, an expression container holding one, or a
+template literal without expressions) on a depth-accepting surface element (today `SurfaceListCard`, or `<ns>.SurfaceListCard`)
+is a finding when a `SurfaceCard`, `SurfaceListCard` or `SurfaceAccordionCard` element of the same file encloses it. A depth
+computed at run time, `depth="nested"`, and a surface no element of the file encloses are not judged. The fix is to drop
+`depth` and let the Grammar resolve it from the surface context.
+
+**Invalid** (`src/components/blocks/Runs/component.tsx`)
+
+```tsx
+<SurfaceCard label="Run">
+  <SurfaceListCard label="Steps" depth="top" items={steps} />
+</SurfaceCard>
+```
+
+**Valid** (`src/components/blocks/Runs/component.tsx`)
+
+```tsx
+<SurfaceCard label="Run">
+  <SurfaceListCard label="Steps" items={steps} />
+</SurfaceCard>
+```
+
+**Finding code:** `FE_RAISED_SURFACE_IN_SURFACE`
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-grammar-core",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "ESLint rules for the core Grammar's component, token and composition contracts.",
   "keywords": [
     "eslint",
@@ -41,7 +41,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@starci/eslint-canon-fe": "9.6.0",
+    "@starci/eslint-canon-fe": "9.6.2",
     "eslint": ">=9",
     "typescript": ">=5.9"
   },

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.16.0
+    version: 0.16.2
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.9.0
+    version: 3.9.2
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.6.0
+    version: 9.6.2
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.16.0
+    version: 0.16.2
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.16.0
+    version: 0.16.2
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.12.0
+    version: 4.12.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5956,3 +5956,26 @@ rules:
         source: owner
         quote: "A Mascot reuses the provenance props of Image and MediaFrame; a Mascot without an assetSlot is a finding (relayed by the nivo-lite app)."
         ruling: "Mascot takes AssetSlotProps (assetSlot, assetSha256, assetPrompt) and emits them as data-asset-* on its root; the lint requires assetSlot on every Mascot."
+  - id: R340
+    code: "FE_RAISED_SURFACE_IN_SURFACE"
+    law: "A Grammar surface that accepts a depth prop (SurfaceListCard) does not pass depth=\"top\" when a SurfaceCard, SurfaceListCard or SurfaceAccordionCard of the same file encloses it: a nested surface is subordinate (outlined, BOUNDARY-5), never raised again (BOUNDARY-6, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); the Grammar resolves the depth from the surface context. A depth computed at run time is not judged."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_RAISED_SURFACE_IN_SURFACE"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-raised-surface-in-surface}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/ui.yaml#FE-UI]
+    templateNa: "A template forces no surface depth; the app composes its surfaces."
+    proves:
+      - packages/eslint-grammar-core/src/surface-depth.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/surface-depth.spec.ts, editions: [lite, full], codes: [FE_RAISED_SURFACE_IN_SURFACE]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/surface-depth.spec.ts, editions: [lite, full], codes: [FE_RAISED_SURFACE_IN_SURFACE]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "A list inside another surface is outlined (BOUNDARY-5, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); SurfaceListCard takes its depth from the surface context (grammar 0.16.2)."
+        ruling: "SurfaceListCard resolves its depth from the surface context like SurfaceCard and SurfaceAccordionCard; an app that forces depth=\"top\" on a surface nested in another surface raises a surface inside a surface, so the lint refuses it."

package/runtime/knowledge/patterns/fe/ui.yaml

@@ -24,7 +24,7 @@ rules:
   - id: FE-UI
     title: Compose the selected Grammar
     kind: mandatory
-    hfsRules: [R93, R244, R313, R314, R315, R316, R317, R318, R319, R320, R338, R339]
+    hfsRules: [R93, R244, R313, R314, R315, R316, R317, R318, R319, R320, R338, R339, R340]
     requirement: |-
       Components compose the selected Grammar through its published entry and props; application CSS carries
       layout only (css.yaml). A missing visual capability is added to that Grammar before the app consumes it.
@@ -92,5 +92,6 @@ rules:
         - FE_CONTROL_HEIGHT
         - FE_GENERATED_ART_OUTSIDE_FRAME
         - FE_MASCOT_ASSET_SLOT_MISSING
+        - FE_RAISED_SURFACE_IN_SURFACE
       manual: []
     relatedExamples: [full-app-shell, lite-app-shell]