@terpjs/contract 0.8.0 → 0.10.0

package/src/routes-codegen.test.js

@@ -8,7 +8,7 @@ import { afterEach, describe, expect, it } from "vitest";
 
 import {
   canonicalPath,
-  extractRoutePaths,
+  extractRoutes,
   generateRouteTable,
   moduleFiles,
   paramNamesOf,
@@ -66,17 +66,17 @@ describe("param extraction from a path", () => {
 
 describe("extraction from a module manifest", () => {
   it("reads every route path a manifest declares", () => {
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       manifest('{ path: "/records", view: "List" }, { path: "/records/:recordId", view: "Detail" }'),
       "module.tsx",
     );
     expect(problems).toEqual([]);
-    expect(paths).toEqual(["/records", "/records/:recordId"]);
+    expect(routes.map((route) => route.path)).toEqual(["/records", "/records/:recordId"]);
   });
 
   it("reads a manifest declared as a property value, not only `export const manifest`", () => {
     // The packaged admin area's shape: defineModuleManifest(...) inside an object literal.
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       [
         'import { defineModuleManifest } from "@terpjs/contract";',
         "export const adminModule = {",
@@ -86,25 +86,25 @@ describe("extraction from a module manifest", () => {
       "module.tsx",
     );
     expect(problems).toEqual([]);
-    expect(paths).toEqual(["/admin"]);
+    expect(routes.map((route) => route.path)).toEqual(["/admin"]);
   });
 
   it("refuses a path that is not a plain string literal, naming file and line", () => {
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       manifest("{ path: `/records/${base}`, view: \"List\" }"),
       "src/modules/records/module.tsx",
     );
-    expect(paths).toEqual([]);
+    expect(routes.map((route) => route.path)).toEqual([]);
     expect(problems).toHaveLength(1);
     expect(problems[0]).toContain("src/modules/records/module.tsx:4");
     expect(problems[0]).toContain("not a plain string literal");
   });
 
   it("refuses a spread route and a non-literal routes array", () => {
-    const spread = extractRoutePaths(manifest("...shared"), "module.tsx");
+    const spread = extractRoutes(manifest("...shared"), "module.tsx");
     expect(spread.problems[0]).toContain("not an object literal");
 
-    const dynamic = extractRoutePaths(
+    const dynamic = extractRoutes(
       [
         'import { defineModuleManifest } from "@terpjs/contract";',
         "export const manifest = defineModuleManifest({ name: \"x\", routes: buildRoutes() });",
@@ -115,20 +115,20 @@ describe("extraction from a module manifest", () => {
   });
 
   it("refuses a module slot with no manifest call at all", () => {
-    const { problems } = extractRoutePaths("export const views = {};", "module.tsx");
+    const { problems } = extractRoutes("export const views = {};", "module.tsx");
     expect(problems[0]).toContain("no defineModuleManifest");
   });
 
   it("refuses a route with no path", () => {
-    const { problems } = extractRoutePaths(manifest('{ view: "List" }'), "module.tsx");
+    const { problems } = extractRoutes(manifest('{ view: "List" }'), "module.tsx");
     expect(problems[0]).toContain("declares no `path`");
   });
 });
 
 describe("rendering the declaration file", () => {
   it("is deterministic: deduped, sorted, LF-only, one trailing newline", () => {
-    const first = renderRouteTable(["/b", "/a", "/b"]);
-    const second = renderRouteTable(["/b", "/b", "/a"]);
+    const first = renderRouteTable([{ path: "/b", search: [] }, { path: "/a", search: [] }, { path: "/b", search: [] }]);
+    const second = renderRouteTable([{ path: "/b", search: [] }, { path: "/b", search: [] }, { path: "/a", search: [] }]);
     expect(first).toBe(second);
     expect(first).not.toContain("\r");
     expect(first.endsWith("}\n")).toBe(true);
@@ -136,14 +136,14 @@ describe("rendering the declaration file", () => {
   });
 
   it("types a parameterised route's params and leaves a paramless route empty", () => {
-    const rendered = renderRouteTable(["/records/:recordId", "/records", "/s/:a/i/:b"]);
+    const rendered = renderRouteTable([{ path: "/records/:recordId", search: [] }, { path: "/records", search: [] }, { path: "/s/:a/i/:b", search: [] }]);
     expect(rendered).toContain('"/records": Record<never, never>;');
     expect(rendered).toContain('"/records/:recordId": { recordId: string };');
     expect(rendered).toContain('"/s/:a/i/:b": { a: string; b: string };');
   });
 
   it("augments the react-core table so the app's own types pick it up", () => {
-    const rendered = renderRouteTable(["/"]);
+    const rendered = renderRouteTable([{ path: "/", search: [] }]);
     expect(rendered).toContain('declare module "@terpjs/react-core"');
     expect(rendered).toContain("interface TerpRouteTable");
     // A module augmentation only applies from a file that IS a module.
@@ -151,6 +151,83 @@ describe("rendering the declaration file", () => {
   });
 });
 
+describe("declared query-string keys", () => {
+  it("reads a route's search keys, and defaults to none", () => {
+    const { routes, problems } = extractRoutes(
+      manifest(
+        '{ path: "/records", view: "List", search: ["status", "page"] }, ' +
+          '{ path: "/records/:recordId", view: "Detail" }',
+      ),
+      "module.tsx",
+    );
+    expect(problems).toEqual([]);
+    expect(routes).toEqual([
+      { path: "/records", search: ["status", "page"] },
+      { path: "/records/:recordId", search: [] },
+    ]);
+  });
+
+  it("refuses keys that cannot be read statically, naming file and line", () => {
+    // Held to the same standard as `path`: a key list assembled at runtime would emit a
+    // table missing a key, which turns a real navigation into a type error.
+    const spread = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: [...FILTERS] }'),
+      "module.tsx",
+    );
+    expect(spread.problems.join("\n")).toMatch(/search` key is not a plain string literal/);
+
+    const dynamic = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: FILTERS }'),
+      "module.tsx",
+    );
+    expect(dynamic.problems.join("\n")).toMatch(/search` is not an array literal/);
+    expect(dynamic.problems[0]).toMatch(/^module\.tsx:4:/);
+  });
+
+  it("refuses a key that is not a plain identifier, because it cannot be a typed property", () => {
+    const { problems } = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: ["not-an-identifier"] }'),
+      "module.tsx",
+    );
+    expect(problems.join("\n")).toMatch(/is not a plain identifier/);
+  });
+
+  it("emits a second table keyed only for routes that declare keys", () => {
+    const rendered = renderRouteTable([
+      { path: "/records", search: ["status"] },
+      { path: "/records/:recordId", search: [] },
+    ]);
+    expect(rendered).toContain('    "/records": Record<never, never>;');
+    expect(rendered).toContain("  interface TerpRouteSearchTable {");
+    expect(rendered).toContain('    "/records": { status?: string };');
+    // The route that declares no keys is absent from the SEARCH table (it is of course
+    // present in the params table above), so passing `search` to it stays a typecheck
+    // error rather than accepting anything.
+    const searchTable = rendered.slice(rendered.indexOf("interface TerpRouteSearchTable"));
+    expect(searchTable).not.toContain("/records/:recordId");
+  });
+
+  it("omits the search table entirely when no route declares a key", () => {
+    // An app that declares none gets exactly the file it had before route search existed
+    // — and no empty interface for its own linter to complain about.
+    const rendered = renderRouteTable([{ path: "/records", search: [] }]);
+    expect(rendered).not.toContain("TerpRouteSearchTable");
+  });
+
+  it("unions the keys when two manifests mount one path", () => {
+    const rendered = renderRouteTable([
+      { path: "/shared", search: ["b"] },
+      { path: "/shared", search: ["a", "b"] },
+    ]);
+    expect(rendered).toContain('    "/shared": { a?: string; b?: string };');
+  });
+
+  it("keys the search table by the canonical spelling, like the params table", () => {
+    const rendered = renderRouteTable([{ path: "/admin/users/$userId", search: ["q"] }]);
+    expect(rendered).toContain('    "/admin/users/:userId": { q?: string };');
+  });
+});
+
 describe("generating across an app's module slots", () => {
   it("merges every slot and dedupes a path two modules claim", () => {
     const root = appWithModules({

package/src/schema.d.ts

@@ -382,6 +382,11 @@ export interface components {
              * Format: uuid
              */
             id: string;
+            /**
+             * Permissions
+             * @default []
+             */
+            permissions: string[];
             /** Role Name */
             role_name: string;
             /** Role Rank */

package/src/tokens.contrast.test.js

@@ -22,6 +22,7 @@ const here = (name) => fileURLToPath(new URL(name, import.meta.url));
 
 const tokensCss = fs.readFileSync(here("./tokens.css"), "utf8");
 const registry = JSON.parse(fs.readFileSync(here("../themes.json"), "utf8"));
+const manifest = JSON.parse(fs.readFileSync(here("./tokens.manifest.json"), "utf8"));
 
 /** WCAG 2.1 AA, normal-size text. Large text and UI boundaries would be 3.0. */
 const AA_NORMAL_TEXT = 4.5;
@@ -35,8 +36,12 @@ const AAA_NORMAL_TEXT = 7;
  * floor to AAA, because WCAG defines no AAA tier for non-text contrast — `minimumContrast` in
  * themes.json is a promise about reading, and inventing a stricter non-text bar from it would
  * be this file asserting a standard nobody wrote.
+ *
+ * Read from the manifest for the same reason `floorFor` is: both bars are published so a theme
+ * editor can hold an app's palette to them, and a bar that is published in one place and
+ * enforced from another is two numbers wearing one name.
  */
-const UI_COMPONENT = 3;
+const UI_COMPONENT = manifest.nonTextMinimumContrast;
 
 /**
  * Pairings the framework renders as text, read from the shared data file.
@@ -186,12 +191,18 @@ function contrastRatio(a, b) {
 }
 
 /**
- * The ratio a theme's pairings must reach. AA for normal text by default; a theme may declare
- * a higher floor in `themes.json`, which is how the high-contrast theme's promise is a gate
- * rather than a sentence in its description.
+ * The ratio a theme's pairings must reach — read from the MANIFEST, not from `themes.json`.
+ *
+ * AA for normal text by default; a theme may declare a higher floor in the registry, which is
+ * how the high-contrast theme's promise is a gate rather than a sentence in its description.
+ * The indirection is the point: the manifest publishes an effective floor per theme so the
+ * Studio's theme editor and an agent can hold an app's own palette to the same bar this gate
+ * holds the framework's. Reading it back here means the published floor and the enforced floor
+ * are one number. Re-deriving it from the registry on this side would let the manifest publish
+ * 4.5 for a theme this file measures at 7 and neither would notice.
  */
 const floorFor = (name) =>
-  registry.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
+  manifest.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
 
 /**
  * Every pairing in *list*, in every registered theme, tagged with its ratchet key and the

package/src/tokens.css

@@ -7,6 +7,10 @@
      text-field carets) into the light palette so it never renders as foreign
      OS-dark chrome. Each theme block below sets its own. */
   color-scheme: light;
+  /* The appearance as something a stylesheet can branch on — see appearanceSwitch above.
+     color-scheme records the same fact and no selector can read it. */
+  --appearance-show-light: block;
+  --appearance-show-dark: none;
   --color-brand-primary: #2563eb;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #1d4ed8;
@@ -77,6 +81,9 @@
   --density-compact-control-min-height: 2rem;
   --density-compact-cell-pad-y: 0.5rem;
   --density-compact-cell-pad-x: 0.5rem;
+  --density-comfortable-control-min-height: 2.25rem;
+  --density-comfortable-cell-pad-y: 0.75rem;
+  --density-comfortable-cell-pad-x: 0.75rem;
   --radius-sm: 0.25rem;
   --radius-md: 0.5rem;
   --radius-lg: 0.75rem;
@@ -88,10 +95,16 @@
   --z-index-base: 0;
   --z-index-sticky: 30;
   --z-index-backdrop: 40;
+  --z-index-skip-link: 45;
   --z-index-drawer: 50;
   --z-index-popover: 60;
   --z-index-tooltip: 70;
   --z-index-toast: 100;
+  --shell-sidebar-width-expanded: 15rem;
+  --shell-sidebar-width-collapsed: 4rem;
+  --shell-header-height: 3rem;
+  --shell-content-max-width: 80rem;
+  --shell-brand-size: 1.75rem;
   --breakpoint-sm: 480px;
   --breakpoint-md: 768px;
   --breakpoint-lg: 1024px;
@@ -130,6 +143,8 @@
    The slate-neutral dark counterpart to light, and the theme the OS dark preference selects. */
 [data-theme='dark'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #1d4ed8;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #2563eb;
@@ -184,6 +199,8 @@
    A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA. */
 [data-theme='midnight'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #0b4ea8;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #1158c7;
@@ -238,6 +255,8 @@
    A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting. */
 [data-theme='twilight'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #5b21b6;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #6d28d9;
@@ -292,6 +311,8 @@
    A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme. */
 [data-theme='contrast'] {
   color-scheme: light;
+  --appearance-show-light: block;
+  --appearance-show-dark: none;
   --color-brand-primary: #0842a0;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #05275a;
@@ -346,6 +367,8 @@
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
     color-scheme: dark;
+    --appearance-show-light: none;
+    --appearance-show-dark: block;
     --color-brand-primary: #1d4ed8;
     --color-brand-primary-contrast: #ffffff;
     --color-brand-primary-hover: #2563eb;

package/src/tokens.manifest.json

@@ -7,31 +7,36 @@
       "name": "light",
       "label": "Light",
       "appearance": "light",
-      "description": "The default. Carries every token, including the geometry the other themes inherit."
+      "description": "The default. Carries every token, including the geometry the other themes inherit.",
+      "minimumContrast": 4.5
     },
     {
       "name": "dark",
       "label": "Dark",
       "appearance": "dark",
-      "description": "The slate-neutral dark counterpart to light, and the theme the OS dark preference selects."
+      "description": "The slate-neutral dark counterpart to light, and the theme the OS dark preference selects.",
+      "minimumContrast": 4.5
     },
     {
       "name": "midnight",
       "label": "Midnight",
       "appearance": "dark",
-      "description": "A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA."
+      "description": "A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA.",
+      "minimumContrast": 4.5
     },
     {
       "name": "twilight",
       "label": "Twilight",
       "appearance": "dark",
-      "description": "A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting."
+      "description": "A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting.",
+      "minimumContrast": 4.5
     },
     {
       "name": "contrast",
       "label": "High contrast",
       "appearance": "light",
-      "description": "A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme."
+      "description": "A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme.",
+      "minimumContrast": 7
     }
   ],
   "tokens": [
@@ -787,6 +792,30 @@
       },
       "themeable": false
     },
+    {
+      "name": "--density-comfortable-control-min-height",
+      "category": "density",
+      "values": {
+        "light": "2.25rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-comfortable-cell-pad-y",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-comfortable-cell-pad-x",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
     {
       "name": "--radius-sm",
       "category": "radius",
@@ -875,6 +904,14 @@
       },
       "themeable": false
     },
+    {
+      "name": "--z-index-skip-link",
+      "category": "zIndex",
+      "values": {
+        "light": "45"
+      },
+      "themeable": false
+    },
     {
       "name": "--z-index-drawer",
       "category": "zIndex",
@@ -907,6 +944,46 @@
       },
       "themeable": false
     },
+    {
+      "name": "--shell-sidebar-width-expanded",
+      "category": "shell",
+      "values": {
+        "light": "15rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-sidebar-width-collapsed",
+      "category": "shell",
+      "values": {
+        "light": "4rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-header-height",
+      "category": "shell",
+      "values": {
+        "light": "3rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-content-max-width",
+      "category": "shell",
+      "values": {
+        "light": "80rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-brand-size",
+      "category": "shell",
+      "values": {
+        "light": "1.75rem"
+      },
+      "themeable": false
+    },
     {
       "name": "--breakpoint-sm",
       "category": "breakpoint",
@@ -1164,6 +1241,7 @@
       "themeable": false
     }
   ],
+  "nonTextMinimumContrast": 3,
   "textPairs": [
     {
       "id": "body-on-card",
@@ -1193,6 +1271,20 @@
       "bg": "--color-neutral-50",
       "layer": "primitive"
     },
+    {
+      "id": "danger-on-card",
+      "label": "danger text on a card",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "danger-on-canvas",
+      "label": "danger text on the canvas",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
+    },
     {
       "id": "primary-button-label",
       "label": "primary button label",
@@ -1339,6 +1431,13 @@
       "fg": "--color-fg-muted",
       "bg": "--color-status-danger-soft",
       "layer": "semantic"
+    },
+    {
+      "id": "sidebar-nav-link-hover",
+      "label": "a hovered sidebar navigation link",
+      "fg": "--color-sidebar-fg",
+      "bg": "--color-sidebar-accent",
+      "layer": "semantic"
     }
   ],
   "nonTextPairs": [

package/src/tokens.manifest.test.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
+import { APPEARANCE_MECHANISM_TOKENS } from "./appearance-mechanism.js";
 import { parseRules } from "./css-rules.js";
 
 // The published token manifest: the same tokens as machine-readable data.
@@ -44,8 +45,22 @@ describe("token manifest", () => {
     // Either direction is a real failure: a token missing from the manifest is invisible to
     // every tool that reads it, and a token in the manifest that the sheet does not declare
     // is a control that would silently do nothing.
+    //
+    // The appearance switch is the exception and is subtracted by name. It is the theme's own
+    // `appearance` in the form a stylesheet can branch on, not a value anyone designs, and its
+    // values are `block` / `none` — a theme editor offering that pair offers a way to break the
+    // switch rather than a way to theme anything. The list is exact, so a third such property
+    // has to arrive here and say the same thing about itself.
     const manifestNames = manifest.tokens.map((token) => token.name).sort();
-    expect(manifestNames).toEqual([...base.keys()].sort());
+    const declaredNames = [...base.keys()].filter(
+      (name) => !APPEARANCE_MECHANISM_TOKENS.includes(name),
+    );
+    expect(manifestNames).toEqual(declaredNames.sort());
+    // And they really are declared — subtracting a name that is not there would hide a
+    // manifest gap rather than an exemption.
+    for (const name of APPEARANCE_MECHANISM_TOKENS) {
+      expect(base.has(name), `${name} is not declared on the base root`).toBe(true);
+    }
   });
 
   it("publishes the theme list the sheet was generated from", () => {
@@ -55,11 +70,12 @@ describe("token manifest", () => {
     expect(manifest.base).toBe(registry.base);
     expect(manifest.systemDark).toBe(registry.systemDark);
     expect(manifest.themes).toEqual(
-      registry.themes.map(({ name, label, appearance, description }) => ({
+      registry.themes.map(({ name, label, appearance, description, minimumContrast }) => ({
         name,
         label,
         appearance,
         description,
+        minimumContrast: minimumContrast ?? 4.5,
       })),
     );
     for (const theme of manifest.themes) {
@@ -67,6 +83,37 @@ describe("token manifest", () => {
     }
   });
 
+  it("publishes an effective contrast floor on every theme, never below AA", () => {
+    // The floor is published as a number on EVERY theme, including the four that take the
+    // default, because the consumer this file exists for is a theme editor holding an app's own
+    // palette to the same bar. A field present only on `contrast` would make the other four
+    // "unknown", and a consumer that guesses is a consumer that can disagree with the gate.
+    //
+    // `tokens.contrast.test.js` reads these numbers rather than the registry, so a wrong value
+    // here does not merely mislead a reader — it moves the bar the framework's own palettes are
+    // measured against, and the theme-list assertion above is what stops it from moving.
+    for (const theme of manifest.themes) {
+      expect(typeof theme.minimumContrast, `${theme.name} floor type`).toBe("number");
+      expect(theme.minimumContrast, `${theme.name} floor`).toBeGreaterThanOrEqual(4.5);
+    }
+    // And the mechanism must still be exercised by at least one theme, or "publishes a floor"
+    // decays into publishing the same constant five times.
+    expect(
+      manifest.themes.filter((theme) => theme.minimumContrast > 4.5).map((t) => t.name),
+    ).not.toEqual([]);
+    // The non-text floor is one number for the whole file, not one per theme, because WCAG
+    // defines no AAA tier for non-text contrast. Published at the top level so the two pairing
+    // sections cannot be read as sharing a bar — and asserted as BELOW every text floor, which
+    // is the relationship a consumer would otherwise have to infer.
+    expect(manifest.nonTextMinimumContrast).toBe(3);
+    for (const theme of manifest.themes) {
+      expect(
+        manifest.nonTextMinimumContrast,
+        `${theme.name}: the non-text bar must not exceed the text bar`,
+      ).toBeLessThan(theme.minimumContrast);
+    }
+  });
+
   it("records the value each token resolves to, in every theme", () => {
     // `values` carries only the themes that declare the token; a theme absent from it inherits
     // the base value. That is the cascade stated as data, so both halves are checked: a

package/src/tokens.themes.test.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
+import { APPEARANCE_MECHANISM_TOKENS } from "./appearance-mechanism.js";
 import { parseRules } from "./css-rules.js";
 
 // The token sheet's theme structure. `tokens.guard.test.ts` in react-core proves every
@@ -132,11 +133,31 @@ describe("token sheet themes", () => {
     // Space, radius, font and shadow are theme-invariant by design: declared once and
     // inherited. Re-declaring one in a single theme is how a theme quietly grows its
     // own spacing scale.
+    //
+    // The appearance switch is the one non-colour that varies per theme, and it is subtracted
+    // by name rather than by a pattern — a prefix exemption would let a whole family through.
     const theme = declarationsFor(selector);
-    const geometry = [...theme.keys()].filter((token) => !isColour(token));
+    const geometry = [...theme.keys()].filter(
+      (token) => !isColour(token) && !APPEARANCE_MECHANISM_TOKENS.includes(token),
+    );
     expect(geometry).toEqual([]);
   });
 
+  it.each(overlayCases)("declares the whole appearance switch in $selector", ({ selector }) => {
+    // The other direction, and the one that matters: half a switch is worse than none. A theme
+    // declaring `show-light` and forgetting `show-dark` inherits the base value for the second,
+    // so a dark theme would display BOTH marks — and the gate above would say nothing, because
+    // subtracting a token from a check is not the same as requiring it.
+    const theme = declarationsFor(selector);
+    const declared = APPEARANCE_MECHANISM_TOKENS.filter((token) => theme.has(token));
+    expect(declared).toEqual(APPEARANCE_MECHANISM_TOKENS);
+    // And exactly one of the two shows, or the switch is not a switch.
+    const shown = APPEARANCE_MECHANISM_TOKENS.filter(
+      (token) => theme.get(token) === "block",
+    );
+    expect(shown).toHaveLength(1);
+  });
+
   it.each([{ name: BASE.name, appearance: BASE.appearance, selector: BASE_SELECTOR }, ...overlayCases])(
     "opts native chrome into the $appearance palette in $selector",
     ({ appearance, selector }) => {