@terpjs/spec 0.25.0 → 0.26.1

package/README.md

@@ -67,17 +67,28 @@ The artifacts:
    extensions, deep-import segments). The portable prohibition rules cite it
    structurally (the `restricted_surface` catalog field); which sanctioned
    component answers each primitive is per-stack configuration.
-7. **The residual ratchet** (`corpus/RESIDUALS.json`) — the statically-erased
+7. **The layout declaration** (`layout-declaration.schema.json`) — the
+   stack-neutral, normative schema for the document an app checks in to declare
+   which slot-typed page contract it opts into, which palette it starts on, and
+   how its application shell is shaped (content measure, density, navigation
+   placement, the navigation groups a module's items name by id, and the mark
+   the app is recognised by). One document, so a build-time checker and the running app read the
+   same bytes and neither can hold a different answer — and so a tool that edits
+   files rather than code can read and rewrite those choices. Naming the contract
+   and naming a palette are the app's to do and their values are per-stack, hence
+   plain strings; the shell's vocabulary is fixed normatively, and the reference
+   stack's resolver is parity-tested against it.
+8. **The residual ratchet** (`corpus/RESIDUALS.json`) — the statically-erased
    or renamed forms deliberately outside the corpus contract, per rule, as
    shrink-only data (see "Detector boundaries" below).
-8. **The scorecard format** (`scorecard.schema.json`) — the machine-readable
+9. **The scorecard format** (`scorecard.schema.json`) — the machine-readable
    certification summary a conformant checker emits (spec version, per-rule
    verdicts over the corpus, residuals claimed), so "certified against spec
    X.Y.Z" is a verifiable artifact instead of a claim.
-9. **The changelog** (`CHANGELOG.md`) — the change history keyed to `VERSION`
+10. **The changelog** (`CHANGELOG.md`) — the change history keyed to `VERSION`
    (the top entry must match, held by the spec suite), so a checker certified
    against an earlier version can see exactly what changed since.
-10. **The rule pages** (`docs/rules/`) — plain-language documentation generated
+11. **The rule pages** (`docs/rules/`) — plain-language documentation generated
     from the catalog (`tools/generate_rule_docs.py`; regenerate-and-compare
     parity in the spec suite, so the pages cannot drift from the data).
 

package/VERSION

@@ -1 +1 @@
-0.25.0
+0.26.1

package/catalog/frontend/layout-contract.json

@@ -2,7 +2,7 @@
   "id": "frontend/layout-contract",
   "surface": "frontend",
   "title": "An opted-in app's archetype body slots accept only the contract's components",
-  "intent": "With a checked-in layout contract, each page archetype's body slot is constrained to the contract's sanctioned components, so screens stay structurally consistent and the failure message tells an agent exactly how to build the screen. Paired with the fail-closed runtime check on the rendered slot.",
+  "intent": "With a checked-in layout declaration, each page archetype's body slot is constrained to the contract's sanctioned components, so screens stay structurally consistent and the failure message tells an agent exactly how to build the screen. Paired with the fail-closed runtime check on the rendered slot. The declaration is the single source for the opt-in, for the palette the app opens on, and for the shell's own shape down to the navigation groups a module's items name by id and the mark the app is recognised by (layout-declaration.schema.json): a build-time checker and the running app read the same document, so neither can enforce a contract the other does not, and a key declared both in the document and in the app's own code is refused rather than resolved by an invisible precedence.",
   "layer": "static-bespoke",
   "enforcement": [
     {
@@ -18,7 +18,7 @@
     }
   ],
   "opt_out": "// terp-allow-layout-contract: <reason>",
-  "reference": "frontend/layout-contract.json + the layoutContract bootstrap option (ADR 0079); verifySlotChildren in @terpjs/react-core is the runtime DOM check.",
+  "reference": "frontend/layout-contract.json, the document layout-declaration.schema.json describes (ADR 0079); the app imports it and the reference stack's bootstrap resolves it, refusing an unknown key, a value outside its enum, and any key declared twice. The per-stack values: contracts are the keys of LAYOUT_CONTRACTS in @terpjs/react-core, and defaultTheme names one of the palettes @terpjs/contract compiles or the reserved system. Neither list is written out here: the contract ids and the palette names both live in @terpjs/react-core's published layout.manifest.json, with the values filled in for the release an app is pinned to, and every copy of them in that stack is gated against it. A fourth copy in this field would be the one nothing checks, and it would sit in the very field this schema points a reader at for the truth. shell.navGroups is groupNav's group table in @terpjs/react-core, whose NavItem.group references it; shell.brand names paths Vite serves from the app's own frontend/public, rendered into AppShell's logo and logoDark slots. verifySlotChildren in @terpjs/react-core is the runtime DOM check.",
   "runtime": {
     "applicability": "required"
   },

package/layout-declaration.schema.json

@@ -0,0 +1,78 @@
+{
+  "title": "Terp Standard - the app's layout declaration",
+  "description": "The normative, stack-neutral schema for the document an app checks in to declare its layout: which slot-typed page contract it opts into, which palette it starts on, and how its application shell is shaped. One document, so a build-time checker and a running app read the same bytes and neither can hold a different answer - and so a tool that edits files, rather than code, can read and rewrite these choices. Naming the contract and naming a palette are the app's to do and the values are per-stack, hence plain strings; the shell's vocabulary is fixed here, because a density or a navigation placement means the same thing on any stack. Every key is optional: an absent key is not a default, it is the app declining to declare, and a consumer must leave whatever was already in force alone. A key a consumer does not recognise must be refused rather than ignored, or a declaration that does nothing looks like one that works.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "contract": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The named slot-typed page contract this app opts into. Which contracts exist, and which components each of their page slots admits, is per-stack configuration recorded non-normatively in the catalog entry's reference field - the portable part is that the opt-in is declared here, once, for every consumer that enforces it."
+    },
+    "defaultTheme": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The palette the app starts on, until a person chooses another and for as long as they have not. Declared here rather than in the app's own code for the reason the shell's shape is: a choice reachable only by editing code is out of reach of anything that edits files, and which palette an app opens on is among the most visible choices its operator makes. Which palettes exist is per-stack configuration recorded non-normatively in the catalog entry's reference field, hence a plain string rather than an enum - the portable part is that the choice is declared here, once. The one reserved name is \"system\", which declares that the app opens on whatever light or dark preference the viewer's own platform reports; every other value names a palette the stack ships, and a consumer must refuse a name it does not ship rather than fall back to one it does."
+    },
+    "shell": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How the application shell is shaped. Separate from the contract above because that governs the inside of a page and this governs the frame around it. Everything in here has a vocabulary this schema fixes, which is what separates it from the two keys above: a density, a navigation placement, the parts of a navigation group and the parts of a brand mark all mean the same thing on any stack, while which page contracts and which palettes exist do not.",
+      "properties": {
+        "brand": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The app's own mark, as paths a consumer resolves the way it resolves any other static asset the app ships. Declared here for the reason everything else in this document is: a mark is among the most visible things about an app and it was reachable only by editing that app's source, which put it out of reach of anything that edits files. Both keys are optional, and an app that declares neither shows whatever placeholder its stack ships.",
+          "properties": {
+            "logo": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The mark shown inside the app's own frame. A consumer sizes it to the frame rather than to itself, so an oversized asset is scaled down rather than clipped."
+            },
+            "logoDark": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The mark for a dark palette, declared separately rather than derived. A mark with fixed colours cannot survive a dark background and no consumer can tell whether this one can, so an app that has a second asset says so and an app that does not says nothing and keeps one mark everywhere. A consumer that has both must choose by the appearance of the palette actually in force, not by the viewer's platform preference: an app may open on a dark palette on a light platform, and a mark chosen by the platform would then be the wrong one."
+            }
+          }
+        },
+        "contentWidth": {
+          "enum": ["full", "measured"],
+          "description": "Whether routed content is capped at the shell's declared reading measure or spans the full track."
+        },
+        "density": {
+          "enum": ["comfortable", "compact"],
+          "description": "The app-wide control height and cell padding, declared once for the whole shell rather than per screen."
+        },
+        "navGroups": {
+          "type": "array",
+          "description": "The navigation groups this app declares, which is the only place they can be declared: a group spans modules, so no module can own one. A module's navigation item names a group by id, an item naming a group this list does not declare is not an error but the normal state of an app mid-adoption, and every such item falls into a trailing group with no label. Declaring two groups with the same id is an authoring error a consumer must refuse.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The group's own name, referenced by a navigation item to say which group it belongs to. Non-empty: a consumer may well treat the empty string as a usable key at render time, where being total matters more than being strict, but declaring one is an authoring error with no legitimate transient form - it is a group nothing can name on purpose."
+              },
+              "label": {
+                "type": "string",
+                "description": "What a consumer renders above the group's list. The empty string declares a positioning-only group: no label element at all, which is how an app places otherwise ungrouped items somewhere other than the end without inventing a heading for them. Required rather than optional, so that having no label is a decision this document states rather than a key someone forgot."
+              },
+              "order": {
+                "type": "integer",
+                "description": "Sort key against sibling groups, ascending. Absent is the same as zero and the sort is stable, so groups that tie keep the order they are declared in - which means an app that wants only a sequence can write the groups in that sequence and set this on none of them. An integer, because a sort key is an ordinal."
+              }
+            }
+          }
+        },
+        "navPlacement": {
+          "enum": ["header", "sidebar"],
+          "description": "Where the primary navigation sits on a wide viewport: a full-height rail beside the content, or a row within the header."
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/spec",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "The Terp Standard — stack-neutral rule catalog, violation corpus, finding format, and refused-surface declaration (ADRs 0080/0081; packaged per ADR 0082, published per ADR 0086). Data only: consumers resolve the spec root via require.resolve('@terpjs/spec/package.json').",
   "files": [
     "VERSION",
@@ -8,6 +8,7 @@
     "app-check-report.schema.json",
     "scorecard.schema.json",
     "assurance-profile.schema.json",
+    "layout-declaration.schema.json",
     "restricted-surface.json",
     "catalog",
     "corpus"