@supertype.ai/foundations 0.1.29 → 0.1.31

package/dist/contrast.d.ts

@@ -19,12 +19,39 @@ export declare function parseColor(value: string): Rgb | null;
 export declare function luminance([r, g, b]: Rgb): number;
 /** WCAG contrast ratio, 1:1 to 21:1. */
 export declare function contrast(a: Rgb, b: Rgb): number;
+/**
+ * APCA lightness contrast (Lc), the perceptual measure WCAG 3 is built on.
+ *
+ * It sits beside `contrast` because the two answer different questions and an
+ * ink ramp needs both. A WCAG ratio is polarity-blind: it reports the same
+ * number whether the text is dark on light or light on dark, when in fact dark
+ * glyphs on a bright field thin out and light glyphs on a dark field bloat. That
+ * blindness is what lets a ramp be ordered by ratio and still read flat — viably
+ * shipped a `--muted-foreground` measuring 72.5 Lc in light and 52.1 in dark,
+ * the same verdict from `contrast` on both sides and twenty points apart to a
+ * reader.
+ *
+ * Lc also states the term a ratio cannot: legibility is contrast times size, so
+ * a floor here is what says an ink comfortable at 16px is or is not comfortable
+ * on the 13px rung a dense product actually spends.
+ *
+ * Returned absolute. It is signed by polarity in the specification, and every
+ * caller so far asks "is this legible", never "which way round is it".
+ */
+export declare function lc(text: Rgb, background: Rgb): number;
 export interface LegibilityFailure {
     theme: Theme;
     ink: string;
     surface: string;
     ratio: number;
     required: number;
+    /**
+     * The token the pair was *supposed* to use, set only when it was undeclared
+     * and the cascade fell through to the next link of its `var()` chain. Without
+     * it a report reads as though the app chose `--primary-foreground` for its
+     * brand fill, when in truth it chose nothing and CSS chose for it.
+     */
+    via?: string;
 }
 /**
  * Every ink on every surface, both themes. Missing or non-literal tokens are
@@ -65,6 +92,13 @@ export interface TokenCuts {
  * a page that is quietly wrong rather than a build that fails.
  */
 export declare function tokenCuts(token: string): TokenCuts;
+/**
+ * The bar a rule owes, held apart from `checkSignals` because it is not a
+ * signal: nothing here carries meaning in its hue, it only has to be seen.
+ */
+export declare function checkHairlines(css: string, { themes }?: {
+    themes?: Theme[] | undefined;
+}): LegibilityFailure[];
 /**
  * The three bars a palette owes, run over the same engine as `checkLegibility`.
  * Without this the numbers in a theme's comments are claims, not measurements.

package/dist/contrast.js

@@ -3,6 +3,12 @@
  * and `.dark` separately measures an intention, and ssite shipped a `.dark` at a
  * healthy 15.7:1 while the page rendered white on white. Build-time only.
  */
+// The tone vocabulary, for the pairs it names. Value import, not just a type:
+// this file measures what `TONE` declares rather than keeping a second list of
+// it. tone.js resolves no React and imports nothing at runtime, so the bare-Node
+// contract this entry point owes still holds — `check-candidates` and the CLI
+// both import it from plain Node.
+import { TONE } from "./tone.js";
 /**
  * Specificity over what token blocks use. `:root` and `.dark` both score 1 —
  * the tie above. `:not(…)` contributes its argument's score, per spec.
@@ -131,9 +137,7 @@ export function parseColor(value) {
     }
     const hex = input.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
     if (hex) {
-        const digits = hex[1].length === 3
-            ? [...hex[1]].map((d) => d + d).join("")
-            : hex[1];
+        const digits = hex[1].length === 3 ? [...hex[1]].map((d) => d + d).join("") : hex[1];
         return [
             parseInt(digits.slice(0, 2), 16),
             parseInt(digits.slice(2, 4), 16),
@@ -158,6 +162,47 @@ export function contrast(a, b) {
     const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
     return (hi + 0.05) / (lo + 0.05);
 }
+/**
+ * APCA lightness contrast (Lc), the perceptual measure WCAG 3 is built on.
+ *
+ * It sits beside `contrast` because the two answer different questions and an
+ * ink ramp needs both. A WCAG ratio is polarity-blind: it reports the same
+ * number whether the text is dark on light or light on dark, when in fact dark
+ * glyphs on a bright field thin out and light glyphs on a dark field bloat. That
+ * blindness is what lets a ramp be ordered by ratio and still read flat — viably
+ * shipped a `--muted-foreground` measuring 72.5 Lc in light and 52.1 in dark,
+ * the same verdict from `contrast` on both sides and twenty points apart to a
+ * reader.
+ *
+ * Lc also states the term a ratio cannot: legibility is contrast times size, so
+ * a floor here is what says an ink comfortable at 16px is or is not comfortable
+ * on the 13px rung a dense product actually spends.
+ *
+ * Returned absolute. It is signed by polarity in the specification, and every
+ * caller so far asks "is this legible", never "which way round is it".
+ */
+export function lc(text, background) {
+    // Screen luminance on APCA's own curve, which is not WCAG's: exponent 2.4 on
+    // the raw channel, with weights of its own.
+    const y = ([r, g, b]) => {
+        const v = 0.2126729 * (r / 255) ** 2.4 +
+            0.7151522 * (g / 255) ** 2.4 +
+            0.072175 * (b / 255) ** 2.4;
+        // Soft clamp near black, where the power curve stops modelling perception.
+        return v < 0.022 ? v + (0.022 - v) ** 1.414 : v;
+    };
+    const [yText, yBackground] = [y(text), y(background)];
+    // Two exponent pairs, one per polarity. This asymmetry is the whole reason Lc
+    // says something a ratio cannot.
+    const s = yBackground > yText
+        ? (yBackground ** 0.56 - yText ** 0.57) * 1.14
+        : (yBackground ** 0.65 - yText ** 0.62) * 1.14;
+    // Below the noise floor the two are the same colour as far as a reader is
+    // concerned, and the offset below would report a spurious 2.7.
+    if (Math.abs(s) < 0.1)
+        return 0;
+    return Math.abs(s > 0 ? (s - 0.027) * 100 : (s + 0.027) * 100);
+}
 const INKS = ["--foreground", "--muted-foreground", "--card-foreground"];
 const SURFACES = ["--background", "--card", "--muted"];
 /**
@@ -200,6 +245,16 @@ const FILLS = [
     "--stone",
     "--fig",
     "--cocoa",
+    // A chart series is a mark like any other, and docs/cli.md has always said so
+    // ("a status dot or a chart bar that cannot be picked out of its background").
+    // Leaving them out of this list is how the sand shipped at 2.18:1 in light and
+    // the taupe at 2.26:1 in dark: a promise in prose that nothing measured.
+    "--chart-1",
+    "--chart-2",
+    "--chart-3",
+    "--chart-4",
+    "--chart-5",
+    "--chart-6",
 ];
 /**
  * A fill has to separate from the page and from a card. Not from `--muted`: a
@@ -209,6 +264,7 @@ const FILLS = [
 const FILL_SURFACES = ["--background", "--card"];
 /** The same hues as words, at the bar body copy is held to. */
 const INKS_TINTED = [
+    "--primary-ink",
     "--success-ink",
     "--warn-ink",
     "--info-ink",
@@ -223,19 +279,106 @@ const INKS_TINTED = [
     "--fig-ink",
     "--cocoa-ink",
 ];
+/**
+ * The tertiary ink, at the 3:1 its own comment in theme.css claims for it —
+ * placeholders and disabled labels, never anything load-bearing. Held here
+ * rather than in `INKS` because 4.5:1 would fail a token that is correct; held
+ * *somewhere* because the sentence stating the bar was the only thing enforcing
+ * it, and light sits at 3.14:1 on --muted with nothing watching the gap.
+ */
+const TERTIARY = ["--subtle-foreground"];
 /**
  * shadcn's shape: `-foreground` is the label printed on the fill, so the pair is
  * measured against itself rather than against the page.
+ *
+ * `--success` and `--warn` joined the list when the tone table stopped making
+ * exceptions of them. A filled status control is a real thing, `Button
+ * tone="warn" variant="solid"` renders one, and white on amber measured 2.44:1
+ * on the dark theme for as long as the pair went unnamed here.
  */
-const ON_FILL = [
-    ["--primary", "--primary-foreground"],
-    ["--secondary", "--secondary-foreground"],
-    ["--destructive", "--destructive-foreground"],
+const ON_SURFACE = [
     ["--accent", "--accent-foreground"],
     ["--card", "--card-foreground"],
     ["--popover", "--popover-foreground"],
     ["--sidebar", "--sidebar-foreground"],
 ];
+/**
+ * Every cut a tone names, read off `TONE` instead of restated here.
+ *
+ * The tone rows used to be five hand-written pairs in the list above, which is
+ * the arrangement the comment on `tokenCuts` warns about: a palette checked
+ * against one taxonomy and declared from another drifts, and `brand` is the
+ * proof. It was in `TONE` from the day the vocabulary landed and never in this
+ * file, so the one tone whose tokens an app supplies was the one tone nothing
+ * measured.
+ *
+ * Parsed rather than shared as data because `TONE` has to stay a table of
+ * literal class strings — Tailwind scans this package as text and generates
+ * only the classes it can read, so a row assembled from a record would style
+ * nothing. Parsing the literal keeps one declaration; a second table would be
+ * the drift all over again.
+ */
+const TONE_CUT = /\[--tone-(fill|ink|hue):([^\]]*)\]/g;
+/**
+ * A cut's `var()` fallback chain, outermost first: `var(--brand,var(--primary))`
+ * is `["--brand", "--primary"]`. The order is the order CSS tries them in.
+ */
+const toneChains = (classes) => {
+    const chains = { fill: [], ink: [], hue: [] };
+    for (const [, cut, value] of classes.matchAll(TONE_CUT))
+        chains[cut] = [...value.matchAll(/--[a-z0-9-]+/g)].map((m) => m[0]);
+    return chains;
+};
+const TONE_CHAINS = Object.entries(TONE).map(([tone, classes]) => [tone, toneChains(classes)]);
+/** The pair a tone names, for the taxonomy `tokenCuts` reports. */
+const ON_FILL = [
+    ...TONE_CHAINS.map(([, c]) => [c.fill[0], c.ink[0]]),
+    ...ON_SURFACE,
+];
+/**
+ * A tone's label on a tone's fill, resolved the way a browser resolves it.
+ *
+ * `checkLegibility` skips a token it cannot find, and that is right: an app that
+ * declares no `--sidebar` has not failed a bar, it has declined a role. But a
+ * token missing *while its siblings are present* is a different animal. The tone
+ * still renders — `var(--brand-foreground,var(--primary-foreground))` simply
+ * moves to the next link — so the control is painted in a pair the app never
+ * chose and skipping it reads as a pass.
+ *
+ * That is how a bronze `--brand` shipped with a white label at 2.80:1: the fill
+ * was declared, the label was not, and nothing measured the pair that actually
+ * reached the screen. So this follows the chain to whichever link is really
+ * there, and measures that. An app declaring a whole tone is measured on its own
+ * tokens; one declaring none falls through to the package's, which are measured
+ * anyway; one declaring half hears about it in the only terms that matter, the
+ * two colours a reader is going to see.
+ */
+function checkToneCuts(css, { themes = ["light", "dark"] } = {}) {
+    const failures = [];
+    for (const theme of themes) {
+        const tokens = resolveTokens(css, theme);
+        const colorOf = (token) => parseColor(tokens[token] ?? "");
+        for (const [, chains] of TONE_CHAINS) {
+            const fill = chains.fill.find((token) => colorOf(token));
+            const ink = chains.ink.find((token) => colorOf(token));
+            if (!fill || !ink)
+                continue;
+            const ratio = contrast(colorOf(ink), colorOf(fill));
+            if (ratio >= 4.5)
+                continue;
+            failures.push({
+                theme,
+                ink,
+                surface: fill,
+                ratio,
+                required: 4.5,
+                // Only when the tone's own ink was not the one that answered.
+                ...(ink === chains.ink[0] ? {} : { via: chains.ink[0] }),
+            });
+        }
+    }
+    return failures;
+}
 /**
  * The cuts a token ships, read off the same three sets `checkSignals` measures.
  *
@@ -254,20 +397,75 @@ export function tokenCuts(token) {
         asInk: INKS_TINTED.find((ink) => ink === `${fill}-ink`),
     };
 }
+/**
+ * A hairline is neither ink nor a mark, so neither bar fits: WCAG exempts a
+ * decorative rule outright, and holding one to 3:1 would draw a box, not a
+ * border. What it owes is symmetry — the same rule has to read as the same
+ * weight in both themes, and it did not: the dark hairline was tuned by hand
+ * (L22's 1.34:1 on --card was rejected as too faint) while the light one was
+ * never measured at all and shipped under the value dark had turned down.
+ *
+ * 1.4:1 is that floor, set just under the pair the themes now agree on. Only
+ * --background and --card: a rule inside a `muted` well sits on a surface that
+ * is itself a wash, and 1.3:1 is the practical floor for that kind of well.
+ */
+const HAIRLINES = ["--border", "--input"];
+const HAIRLINE_SURFACES = ["--background", "--card"];
+/**
+ * The sidebar keeps its own pair, because a rule there is drawn on `--sidebar`
+ * and never on the page. Measuring it against `--background` would fail a border
+ * that is correct and pass one that is not.
+ */
+const SIDEBAR_HAIRLINE = [
+    "--sidebar-border",
+    "--sidebar",
+];
+/**
+ * The bar a rule owes, held apart from `checkSignals` because it is not a
+ * signal: nothing here carries meaning in its hue, it only has to be seen.
+ */
+export function checkHairlines(css, { themes = ["light", "dark"] } = {}) {
+    return [
+        ...checkLegibility(css, {
+            inks: HAIRLINES,
+            surfaces: HAIRLINE_SURFACES,
+            minimum: 1.4,
+            themes,
+        }),
+        ...checkLegibility(css, {
+            inks: [SIDEBAR_HAIRLINE[0]],
+            surfaces: [SIDEBAR_HAIRLINE[1]],
+            minimum: 1.4,
+            themes,
+        }),
+    ];
+}
 /**
  * The three bars a palette owes, run over the same engine as `checkLegibility`.
  * Without this the numbers in a theme's comments are claims, not measurements.
  */
 export function checkSignals(css, { themes = ["light", "dark"] } = {}) {
     return [
-        ...checkLegibility(css, { inks: FILLS, surfaces: FILL_SURFACES, minimum: 3, themes }),
+        ...checkLegibility(css, {
+            inks: FILLS,
+            surfaces: FILL_SURFACES,
+            minimum: 3,
+            themes,
+        }),
         ...checkLegibility(css, { inks: INKS_TINTED, themes }),
-        ...ON_FILL.flatMap(([fill, label]) => checkLegibility(css, { inks: [label], surfaces: [fill], themes })),
+        ...checkLegibility(css, { inks: TERTIARY, minimum: 3, themes }),
+        ...ON_SURFACE.flatMap(([fill, label]) => checkLegibility(css, { inks: [label], surfaces: [fill], themes })),
+        ...checkToneCuts(css, { themes }),
     ];
 }
 /** A one-line report per failure, for a test's assertion message. */
 export function formatFailures(failures) {
     return failures
-        .map((f) => `${f.theme}: ${f.ink} on ${f.surface} is ${f.ratio.toFixed(2)}:1, below ${f.required}:1`)
+        .map((f) => {
+        const measured = `${f.theme}: ${f.ink} on ${f.surface} is ${f.ratio.toFixed(2)}:1, below ${f.required}:1`;
+        return f.via
+            ? `${measured} — ${f.via} is not declared, so ${f.surface} took ${f.ink} from the fallback`
+            : measured;
+    })
         .join("\n");
 }

package/dist/eslint.d.ts

@@ -20,11 +20,27 @@ export declare function colourRules({ accents, }?: ColourOptions): RestrictedSyn
  */
 export declare function themeOverrideRules(): RestrictedSyntax[];
 /**
- * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
- * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ * `--muted` is a fill at L92%, so `text-muted` lands at ~1.1:1. Invisible, and
+ * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
+ * role.
  */
 export declare function surfaceAsInkRules(): RestrictedSyntax[];
 export declare function renamedTokenRules(): RestrictedSyntax[];
+/**
+ * `render={<a href="…" />}` on a component that takes an `href`. It reads as a
+ * styling choice and is a routing one: the cloned anchor skips the router, so
+ * the page fully reloads and the view transition is lost, and an off-site href
+ * never grows a `rel`. Button, Badge and Card each decide internal vs external
+ * from the href itself, so the anchor is never needed and cannot be right more
+ * often than the one shared rule is.
+ *
+ * Narrow on both axes, so it never fires on a line that is correct. Only those
+ * three components — `RailLink` deliberately takes a router element through
+ * `render`, because its module has to stay importable without Next. And only a
+ * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
+ * so it is not a bug.
+ */
+export declare function linkRules(): RestrictedSyntax[];
 export interface TypographyOptions {
     /** Three-weight ramp. Off for editorial, where 700 is a register not a shout. */
     weights?: boolean;
@@ -40,7 +56,7 @@ export interface TypographyOptions {
     /**
      * Flag a size class on a primitive that already owns a size axis. Off by
      * default for the same reason as `pairing`: it fails until the consumer has
-     * migrated, and the migration is the point.
+     * migrated, and that migration is the intended end state.
      */
     axis?: boolean;
 }
@@ -48,7 +64,7 @@ export declare function typographyRules({ weights, ramp, pairing, axis, }?: Typo
 /**
  * Every design rule, as one list.
  *
- * The five builders below it are still exported, and spreading them by hand is
+ * The builders below it are still exported, and spreading them by hand is
  * what both consumers were doing — one of them into a flat config, the other
  * into a legacy `.eslintrc`, and *both* of them had quietly left out
  * `renamedTokenRules`, so neither would have flagged a deprecated token name.

package/dist/eslint.js

@@ -39,22 +39,49 @@ export function themeOverrideRules() {
     return rule(`/(^| )dark:(${COLOUR_PREFIX})-(${TOKEN})($| )/`, "A `dark:` override on a token means the token is wrong — fix it in theme.css, where one change covers every call site, rather than here. Alpha variants (dark:bg-destructive/20) stay legal: those tune a wash's density, not the token.");
 }
 /**
- * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
- * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ * `--muted` is a fill at L92%, so `text-muted` lands at ~1.1:1. Invisible, and
+ * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
+ * role.
  */
 export function surfaceAsInkRules() {
     return rule("/(^| )(dark:|hover:|focus:|group-hover:)*text-(muted|card|popover|input)($| )/", "That is a surface token, not an ink — as text it has no defined contrast (text-muted measures ~1.1:1 on a light page). Use text-muted-foreground for secondary ink, text-subtle-foreground for tertiary, or text-card-foreground on a card.");
 }
 /**
  * `-foreground` means the label printed on a fill; `-ink` means the hue as
- * words. `warn-foreground` and the eight categorical `-foreground` tokens were
- * always inks, under the other name. The old spellings still resolve, so nothing
- * breaks on the day of the rename; this is what stops them surviving it.
+ * words. The eight categorical `-foreground` tokens were always inks, under the
+ * other name. The old spellings still resolve, so nothing breaks on the day of
+ * the rename; this is what stops them surviving it.
+ *
+ * `warn` left this list when the status tones gained real on-fill labels:
+ * `--warn-foreground` now means what its name says, the ink printed on the warn
+ * fill, and `Button tone="warn" variant="solid"` is what reads it.
  */
-const RENAMED_INKS = "warn|terracotta|ochre|moss|fern|sage|stone|fig|cocoa";
+const RENAMED_INKS = "terracotta|ochre|moss|fern|sage|stone|fig|cocoa";
 export function renamedTokenRules() {
     return rule(`/(^| )(dark:|hover:|focus:|group-hover:)*(text|bg|border|ring|fill|stroke|decoration)-(${RENAMED_INKS})-foreground($| )/`, "That is the deprecated name for the same hue's `-ink`. In this package `-foreground` is the label printed on a fill and `-ink` is the hue used as words, and none of these hues has a printed-on label — they are checked at 4.5:1 against the page, and printing one on its own fill measures about 1.2:1. Use `-ink`.");
 }
+/**
+ * `render={<a href="…" />}` on a component that takes an `href`. It reads as a
+ * styling choice and is a routing one: the cloned anchor skips the router, so
+ * the page fully reloads and the view transition is lost, and an off-site href
+ * never grows a `rel`. Button, Badge and Card each decide internal vs external
+ * from the href itself, so the anchor is never needed and cannot be right more
+ * often than the one shared rule is.
+ *
+ * Narrow on both axes, so it never fires on a line that is correct. Only those
+ * three components — `RailLink` deliberately takes a router element through
+ * `render`, because its module has to stay importable without Next. And only a
+ * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
+ * so it is not a bug.
+ */
+export function linkRules() {
+    return [
+        {
+            selector: 'JSXOpeningElement[name.name=/^(Button|Badge|Card)$/] > JSXAttribute[name.name="render"] > JSXExpressionContainer > JSXElement > JSXOpeningElement[name.name="a"]',
+            message: "Pass `href` instead of rendering an anchor. A cloned <a> bypasses the router (full page load, no view transition) and gets no rel on an off-site href; `href` routes through the package's one rule. `render` is for an element that is not a link.",
+        },
+    ];
+}
 export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 / text-xs 12 / text-sm 14 / text-base 16 and up", pairing = false, axis = false, } = {}) {
     return [
         // Alpha ink composites against whatever surface it lands on, so its
@@ -100,7 +127,7 @@ export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2x
             ? [
                 {
                     selector: 'JSXElement:has(>JSXOpeningElement[name.name="TypographyP"]) ~ JSXElement > JSXOpeningElement[name.name="TypographyProseList"]',
-                    message: "A ui paragraph over a prose list splits one passage across two rungs. Promote the paragraph with TypographyProse, or drop the list to the paragraph's rung with TypographyList variant=\"ui\".",
+                    message: 'A ui paragraph over a prose list splits one passage across two rungs. Promote the paragraph with TypographyProse, or drop the list to the paragraph\'s rung with TypographyList variant="ui".',
                 },
             ]
             : []),
@@ -113,6 +140,7 @@ export function designRules({ accents, typography = true, ...type } = {}) {
     return [
         ...colourRules({ accents }),
         ...(typography ? typographyRules(type) : []),
+        ...linkRules(),
         ...themeOverrideRules(),
         ...surfaceAsInkRules(),
         ...renamedTokenRules(),
@@ -136,10 +164,7 @@ export function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], ...options } =
             name: "@supertype.ai/foundations/design",
             files,
             rules: {
-                "no-restricted-syntax": [
-                    "error",
-                    ...designRules(options),
-                ],
+                "no-restricted-syntax": ["error", ...designRules(options)],
             },
         },
     ];

package/dist/essay/layout.d.ts

@@ -5,7 +5,7 @@ import type { TocHeading } from "./toc.js";
  * moment an aside appeared, setting body copy on a different axis per page.
  * The measure grows per step — a comfortable line length is a range.
  *
- * The margin track is what the third one buys, and it only exists if the
+ * The margin track is what the third one buys, and appears only where the
  * container can pay for it:
  *
  *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter

package/dist/essay/layout.js

@@ -6,7 +6,7 @@ import { ReadingRail } from "./reading.js";
  * moment an aside appeared, setting body copy on a different axis per page.
  * The measure grows per step — a comfortable line length is a range.
  *
- * The margin track is what the third one buys, and it only exists if the
+ * The margin track is what the third one buys, and appears only where the
  * container can pay for it:
  *
  *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter

package/dist/essay/rail.d.ts

@@ -10,6 +10,16 @@ export declare function RailLink({ active, nested, className, children, render,
     /** A sub-heading under the item above it, indented a step further in. */
     nested?: boolean;
     children: ReactNode;
-    /** Swap the anchor for another link element, e.g. `<Link href={…} />`. */
+    /**
+     * Swap the anchor for another link element, e.g. `<Link href={…} />`.
+     *
+     * The one link in the package that does NOT take an `href` and route it
+     * itself, and deliberately: this module is reached from `contents.tsx`,
+     * `reading.tsx` and `layout.tsx`, which a consumer imports in bare Node and in
+     * a test runner with no Next installed. Importing ../href.ts here would put
+     * `next/link` on that path — test/essay-toc.test.ts is what holds the line.
+     * The rail's own links are `#hash` anchors, which want no router anyway; a
+     * rail of routes passes the router's Link through `render`.
+     */
     render?: ReactElement<ComponentProps<"a">>;
 }): import("react").JSX.Element;

package/dist/essay/scroll.js

@@ -1,7 +1,7 @@
 "use client";
 import { useEffect, useState, useSyncExternalStore } from "react";
 /**
- * Reading progress 0→1 from one shared listener: a page mounts both the bar and
+ * Reading progress, 0 to 1, from one shared listener: a page mounts both the bar and
  * the rail, and hook-local state would double every subscription. Reads coalesce
  * to a frame, since `scrollHeight` forces layout.
  */

package/dist/href.d.ts

@@ -0,0 +1,42 @@
+import type { ComponentProps, ReactElement } from "react";
+/**
+ * Where a link goes, decided once.
+ *
+ * This branch — scheme test, router `Link` or plain `<a>`, `rel` on the way out
+ * — was written three times: Card, TypographyLink, and (by omission) every call
+ * site that reached for `render={<a href="…" />}` because the component it was
+ * calling had no `href` of its own. The last of those is the expensive copy: it
+ * looks like a styling escape hatch and is actually a routing decision, made at
+ * the call site, wrongly. A hero CTA written that way full-page-reloads past the
+ * router and drops the view transition, and nothing in the type system says so.
+ *
+ * So components take `href`, not an anchor. `render` stays for what it is for:
+ * an element that is genuinely not an anchor.
+ */
+/** A scheme (`mailto:`, `https:`) means the href leaves the app entirely. */
+export declare function isExternalHref(href: string): boolean;
+export type LinkBehavior = {
+    /** Override the scheme sniff: an absolute URL that is home, or a relative one that is not. */
+    external?: boolean;
+    /**
+     * Defaults on for an http(s) href, off for everything else — `mailto:` and
+     * `tel:` hand off to another app and have no tab to open.
+     */
+    newTab?: boolean;
+};
+/** `Link` requires its own href; as far as a call site here goes it is an anchor. */
+type AnchorComponent = (props: ComponentProps<"a">) => ReactElement | null;
+export type ResolvedLink = {
+    Component: AnchorComponent | "a";
+    /** Spread onto the element: the href, plus `target`/`rel` when it opens away. */
+    props: ComponentProps<"a">;
+    /** For a caller that renders differently for an off-site link — an arrow glyph, an icon. */
+    external: boolean;
+};
+/**
+ * A same-page hash is the one internal href that stays a plain anchor: routing
+ * `#section` through the router asks for a navigation and a view transition to
+ * reach a place the browser can already scroll to.
+ */
+export declare function resolveLink(href: string, { external, newTab }?: LinkBehavior): ResolvedLink;
+export {};

package/dist/href.js

@@ -0,0 +1,63 @@
+import { Link } from "next-view-transitions";
+/**
+ * Where a link goes, decided once.
+ *
+ * This branch — scheme test, router `Link` or plain `<a>`, `rel` on the way out
+ * — was written three times: Card, TypographyLink, and (by omission) every call
+ * site that reached for `render={<a href="…" />}` because the component it was
+ * calling had no `href` of its own. The last of those is the expensive copy: it
+ * looks like a styling escape hatch and is actually a routing decision, made at
+ * the call site, wrongly. A hero CTA written that way full-page-reloads past the
+ * router and drops the view transition, and nothing in the type system says so.
+ *
+ * So components take `href`, not an anchor. `render` stays for what it is for:
+ * an element that is genuinely not an anchor.
+ */
+/** A scheme (`mailto:`, `https:`) means the href leaves the app entirely. */
+export function isExternalHref(href) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+/**
+ * What a wrong `href` is worth saying out loud.
+ *
+ * A value exported from a `"use client"` module and imported by a server
+ * component arrives as a boundary stub — a function that throws when called —
+ * rather than the string it is in the client bundle. Passing one here read as
+ * `TypeError: href.startsWith is not a function`, which React reported with an
+ * empty stack: no component, no file, and every route in the app failing at once
+ * because the offending link sat in a layout.
+ *
+ * The value is the diagnosis, so it goes in the message. `String()` on that stub
+ * prints the "Attempted to call X() from the server" text React put there, which
+ * names the export and the boundary in one line.
+ */
+function assertHref(href) {
+    if (typeof href === "string")
+        return;
+    const seen = typeof href === "function"
+        ? `a function: ${String(href).replace(/\s+/g, " ").slice(0, 160)}`
+        : `${typeof href}: ${JSON.stringify(href)}`;
+    throw new TypeError(`href must be a string, and this one is ${seen}. A function here is usually ` +
+        `a value exported from a "use client" module and imported by a server ` +
+        `component, which crosses the boundary as a stub rather than a string. ` +
+        `Move the constant to a plain module and import it from both sides.`);
+}
+/**
+ * A same-page hash is the one internal href that stays a plain anchor: routing
+ * `#section` through the router asks for a navigation and a view transition to
+ * reach a place the browser can already scroll to.
+ */
+export function resolveLink(href, { external, newTab } = {}) {
+    assertHref(href);
+    const leavesApp = external ?? isExternalHref(href);
+    const away = leavesApp && (newTab ?? href.startsWith("http"));
+    const inPage = !leavesApp && href.startsWith("#");
+    return {
+        Component: leavesApp || inPage ? "a" : Link,
+        props: {
+            href,
+            ...(away ? { target: "_blank", rel: "noopener noreferrer" } : {}),
+        },
+        external: leavesApp,
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { cn } from "./cn.js";
-export { toneClass, impliedTone, type Tone } from "./tone.js";
+export { toneClass, impliedTone, INK_ON_FILL, INK_ON_CARD, INK_ON_POPOVER, INK_ON_SIDEBAR, inkOnSurfaceStyle, type Tone, } from "./tone.js";
+export { resolveLink, isExternalHref, type LinkBehavior, type ResolvedLink, } from "./href.js";
 export * from "./typography/index.js";

package/dist/index.js

@@ -1,9 +1,13 @@
 export { cn } from "./cn.js";
 // The semantic colour vocabulary. Exported from the root because typography
-// takes it too — a link has a tone, and it is the same seven a button has.
+// takes it too: a link has a tone, drawn from the same seven a button has.
 // `toneClass` only: the raw table and its derived half used to ship separately,
 // and the order they were combined in was load-bearing.
-export { toneClass, impliedTone } from "./tone.js";
+export { toneClass, impliedTone, INK_ON_FILL, INK_ON_CARD, INK_ON_POPOVER, INK_ON_SIDEBAR, inkOnSurfaceStyle, } from "./tone.js";
+// Where an href goes, for the rare call site that styles someone else's element
+// and cannot render a Card/Button/TypographyLink — the same pairing with
+// `buttonVariants`. Prefer passing `href` to a component over calling this.
+export { resolveLink, isExternalHref, } from "./href.js";
 export * from "./typography/index.js";
 // NOTE: blocks, the MDX map, and the Shiki plugin are all deliberately absent
 // from this barrel.