@tenphi/cookbook 0.32.0 → 0.33.0

package/docs/customization-rules.md

@@ -109,9 +109,9 @@ imports, configuration, and rendering setup when adapting them.
   [style properties](./upstream/tasty/docs/styles.md): syntax and property reference.
 * [Tasty methodology](./upstream/tasty/docs/methodology.md) and
   [configuration](./upstream/tasty/docs/configuration.md): component design and shared settings.
-* [Glaze methodology](./upstream/glaze/docs/methodology.md): semantic palettes
+* [Glaze methodology](./upstream/glaze/docs/methodology.mdx): semantic palettes
   and contrast relationships.
-* [Glaze API](./upstream/glaze/docs/api.md): color inputs, schemes, and contrast solving.
+* [Glaze API reference](./upstream/glaze/docs/reference/index.md): color inputs, schemes, and contrast solving.
 
 ## Documentation in the installed package
 
@@ -123,9 +123,11 @@ references. These match the dependencies used to build that Cookbook release;
 consumer dependency overrides can change the installed runtime independently.
 
 In the packaged copies, links to available upstream reference pages point to
-these local snapshots. The Markdown references work offline. Links to source
-code and artwork absent from the npm packages point to their upstream release
-and still need internet access. The published website keeps its online links.
+these local snapshots. The Markdown references work offline. Glaze's guides
+are MDX: their prose, code, and tables read offline, but their live examples
+render only on the Glaze website. Links to source code and artwork absent from
+the npm packages point to their upstream release and still need internet
+access. The published website keeps its online links.
 
 Start at `node_modules/@tenphi/cookbook/docs/customization-rules.md`. When the
 package manager uses a different layout, resolve the exported documentation

package/docs/migration.md

@@ -4,7 +4,6 @@ description: Version-specific changes, runtime upgrades, and documentation-sourc
 sidebar:
   order: 9
 ---
-
 Upgrade the Cookbook runtime with your package manager, then apply the notes
 for every version range you cross, starting with the oldest.
 
@@ -25,8 +24,7 @@ npm run preview
 For pnpm use `pnpm add`; for Yarn use `yarn add`. Commit the package manifest and
 package-manager lockfile together. Keep Astro inside Cookbook's declared peer
 range. Review the preview with your custom styles, plugins, fonts, languages,
-and versions before deploying. After deployment, run `cookbook check-build
---url https://docs.example.com/` against that exact build output.
+and versions before deploying. After deployment, run `cookbook check-build --url https://docs.example.com/` against that exact build output.
 
 The creator starts new projects; rerunning it over an existing project is not
 an upgrade path. Generated sites include `.agents/skills/upgrade-cookbook/`
@@ -41,6 +39,34 @@ upgrade the site's Cookbook runtime or package-manager dependencies. Commit the
 documentation lock separately when intentionally updating imported content.
 Local Markdown needs no lock update.
 
+## 0.32.x to 0.33
+
+Cookbook now generates themes with Glaze 3. Generated colors can move slightly;
+check custom palettes in every appearance. See the
+[Glaze 3 upgrade notes](./upstream/glaze/docs/migration.md#upgrading-glaze).
+
+* **Shadows.** A shadow's `intensity` is now an exact tone step, and `fg` is
+  the element casting the shadow rather than a contrast reference. The built-in
+  `shadow` role steps 8 tones in light and dark and is transparent in high
+  contrast. In the default contrast mode, light shadows look as before and dark
+  ones are noticeably stronger, since 2.x stepped only about 3 tones on a dark
+  page. A numeric `theme.contrastLevel` now fades the light shadow toward its
+  high-contrast value instead of strengthening it. Re-tune custom `shadow`
+  roles: drop `fg: "text"` and set `intensity` to the number of tones you want,
+  with `0` in high contrast for a shadow on the page.
+* **Unreachable steps.** A step can't pass black, and the default dark page
+  sits about 9 tones above it. Glaze paints a step that doesn't fit at full
+  strength and logs a "cannot reach" warning. On the default surface, the
+  built-in shadow does this with a `darkTone` dark end below about 14
+  (including `false`) or a numeric `theme.contrastLevel` from about 25 to 99.
+* **Shadow tuning.** `saturationFactor`, `maxSaturation`, `lightnessFactor`,
+  `lightnessBounds`, `minGapTarget`, `alphaMax`, and `bgHueBlend` are gone and
+  fail validation, in `theme.glaze.shadowTuning` and in a role's own `tuning`.
+  The new fields are `objectInfluence`, `tint`, `reach`, and `hueBleed`. There
+  is no opacity cap: lower `intensity` for a lighter shadow.
+* **Glows.** Palette roles accept Glaze `glow` declarations, which lighten
+  `bg` by an exact tone step. Tune each glow with its own `tuning`.
+
 ## Upcoming custom-element naming
 
 All Cookbook-owned custom elements now use the `cookbook-*` prefix, including
@@ -66,11 +92,11 @@ Cookbook now uses Tasty 3.14 and the Tasty ESLint plugin 1.12. Built-in themes
 need no configuration migration. Review custom styles for these changes from
 Tasty 3.12:
 
-- Color opacity suffixes such as `#accent-text.5` now emit `color-mix()`. If the
+* Color opacity suffixes such as `#accent-text.5` now emit `color-mix()`. If the
   palette color is already translucent, the suffix multiplies its alpha rather
   than replacing it. For `#accent-text.$fade`, set `$fade` to a number such as
   `".5"`, rather than a percentage such as `"50%"`.
-- `false` now omits spacing, size, and `outlineOffset` declarations. Use an
+* `false` now omits spacing, size, and `outlineOffset` declarations. Use an
   explicit value such as `"0"` or `"auto"` if a custom style relied on the old
   implicit default. `transition: "none"` now correctly disables transitions,
   including the built-in reduced-motion states.
@@ -145,19 +171,19 @@ A package page still shows an edit link when its own frontmatter sets
 These releases need no configuration changes, but they can affect custom
 scripts, hard-coded links, and apps that share the reader's appearance:
 
-- **Client navigation (0.24):** internal links swap pages without a full
+* **Client navigation (0.24):** internal links swap pages without a full
   reload. Bundled scripts are not rerun after a client navigation, so attach
   custom browser behavior through custom-element lifecycle callbacks or
   initialize it on `astro:page-load`. See
   [client navigation](./site-navigation.md#client-navigation).
-- **Prefetching (0.25):** Astro's hover and focus prefetching is enabled by
+* **Prefetching (0.25):** Astro's hover and focus prefetching is enabled by
   default. Set `prefetch: false` in the Astro configuration to turn it off;
   explicit Astro `prefetch` settings are preserved.
-- **Page URLs (0.25.1):** page URLs follow Astro's `trailingSlash` and
+* **Page URLs (0.25.1):** page URLs follow Astro's `trailingSlash` and
   `build.format`. With the default directory output, internal links, canonicals,
   and `llms.txt` use a trailing slash, such as `/guide/`. See
   [deployment](./deployment.md#public-url-and-base-path).
-- **Appearance storage (0.25.4):** the reader's color scheme and contrast are
+* **Appearance storage (0.25.4):** the reader's color scheme and contrast are
   stored together in one `cookbook-appearance` entry. A scheme saved under the
   previous `cookbook-theme` key is still read and moves to the new entry on the
   next change. See [reader appearance](./theme-and-components.md#reader-appearance).
@@ -311,41 +337,41 @@ choices are ignored; visitors who relied on one can select their scheme again.
 
 These changes were introduced in 0.18:
 
-- **Google fonts:** family-name shorthand loads preset weights and italics and
+* **Google fonts:** family-name shorthand loads preset weights and italics and
   self-hosts the files. The initial build requires network access. Preserve the
   Astro font cache for offline rebuilds, use local files for checked-in assets,
   or select `theme.fontLoading.google: "remote"` for CDN delivery. Weights set
   through CSS variables that cannot be resolved from presets require explicit
   `weights`. See [fonts](./fonts-and-typography.md#change-font-families).
-- **Colors:** body tone 0 and heading tone 4 remain the reading defaults.
+* **Colors:** body tone 0 and heading tone 4 remain the reading defaults.
   The default logo uses fixed Glaze colors (`logo-surface` and `logo-mark`), so
   its book stays light in dark mode. Customize these independently of accents.
   Additional semantic-pair checks may reject custom colors that previously
   passed. Follow the named pair and mode in the diagnostic; see
   [contrast troubleshooting](./troubleshooting.md#contrast-failures).
-- **Header controls:** round controls use `$header-control-radius`, independently
+* **Header controls:** round controls use `$header-control-radius`, independently
   of `$radius`. Set the new token to your preferred radius to keep your previous
   header shape.
-- **Drafts:** production builds retain draft pages at direct URLs and mark them
+* **Drafts:** production builds retain draft pages at direct URLs and mark them
   `noindex`. They are omitted from generated navigation, search, sitemaps, and
   agent indexes. A draft is public to anyone with the URL; use host access
   controls for private previews.
-- **Plugins:** custom metadata is available to route middleware and through
+* **Plugins:** custom metadata is available to route middleware and through
   Cookbook's content API. Plugins that need Astro's synthetic content files or
   inject their own CSS require adaptation. See the tested
   [extension guide](./plugins.md).
-- **Styles:** rendered inline styles are rejected. Move custom styling to Tasty
+* **Styles:** rendered inline styles are rejected. Move custom styling to Tasty
   and registered theme style trees. Keep these components server-rendered;
   browser scripts and `client:*` islands cannot import Cookbook styling, Tasty,
   or Glaze. Attach interaction scripts to the static markup. Isolated,
   sandboxed `Preview` content is the
   documented exception. The new surface inventory is in
   [Component styles](./component-styles.md).
-- **Page text:** the footer offers copy/download Markdown by default. Set
+* **Page text:** the footer offers copy/download Markdown by default. Set
   `site.seo.copyPage: false` to disable the controls and generated page files.
   Configure static host headers if raw Markdown must be excluded from indexing;
   see [deployment](./deployment.md).
-- **Validation:** existing projects can add
+* **Validation:** existing projects can add
   `"validate": "cookbook doctor && astro build && cookbook check-build"`
   to their scripts. `doctor` is explicitly a preflight; successful MDX compilation
   and deployment require the later checks.
@@ -377,29 +403,29 @@ The Appearance panel combines the color scheme and contrast controls in
 The shared-configuration and source-identity changes shipped in **0.14.0**.
 Apply these steps if your project still uses the earlier contracts:
 
-- Move generated inline documentation configuration to `docs.config.ts` and use
+* Move generated inline documentation configuration to `docs.config.ts` and use
   `cookbook()` in Astro. Existing explicit `cookbook({ config })` remains valid,
   but CLI commands read the shared configuration file.
-- For nested Astro apps, put `root: "../.."` in `docs.config.ts`; paths resolve
+* For nested Astro apps, put `root: "../.."` in `docs.config.ts`; paths resolve
   relative to that file. Individual sources may now specify `root` and `id`.
-- Run `cookbook update` after changing a requested npm specifier. A lock for
+* Run `cookbook update` after changing a requested npm specifier. A lock for
   another range or tag is no longer accepted by package name alone.
-- `rawHtml: "sanitize"` preserves safe HTML and removes executable markup and
+* `rawHtml: "sanitize"` preserves safe HTML and removes executable markup and
   presentational attributes. Use `"strip"` for the former removal behavior;
   removal now emits a diagnostic. `"reject"` still fails validation.
-- Unrecognized page frontmatter is kept in graph entry `metadata`. Use
+* Unrecognized page frontmatter is kept in graph entry `metadata`. Use
   `content.frontmatter: "reject"` for the former strict behavior. Cookbook's
   recognized fields retain their validation.
-- `slug` is now relative to the source mount, including when it starts with `/`.
+* `slug` is now relative to the source mount, including when it starts with `/`.
   Use a separate source mount for an unrelated public route.
-- Repeated files in separate source declarations create separate entries.
+* Repeated files in separate source declarations create separate entries.
   Give mounts stable IDs and use `source:<id>/<source-path>` for explicit links.
   `entryBySource(path)` returns `undefined` for an ambiguous path; pass a source
   ID as its second argument. Graph entry IDs include the source ID.
-- Unknown names in `theme.styles` are errors. Register user-authored component
+* Unknown names in `theme.styles` are errors. Register user-authored component
   styles in `theme.customStyles`. Built-in component names and sub-elements
   provide strict editor checking; style objects still contain only overrides.
-- `Tabs` now expects `Tab` children with accessible labels. It provides keyboard
+* `Tabs` now expects `Tab` children with accessible labels. It provides keyboard
   navigation and panels; use an ordinary custom component for a grouping layout.
 
 See [authoring](./authoring.mdx) for component usage and

package/docs/theme-and-components.md

@@ -177,11 +177,12 @@ The names `current`, `constructor`, and `prototype` are reserved.
 Declaring a built-in name intentionally overrides that role; use a project
 prefix for additional roles to avoid future naming collisions.
 
-When a status role such as `info` uses a mix or shadow definition, its derived
-`info-text` defaults to neutral, contrast-corrected text. Override `info-text`
-explicitly for a colored label; the mix/shadow dependency graph stays intact.
-A shadow status also uses a neutral derived surface, because Glaze does not allow
-a shadow to be a mix target. Override the surface separately when needed.
+When a status role such as `info` uses a mix, shadow, or glow definition, its
+derived `info-text` defaults to neutral, contrast-corrected text. Override
+`info-text` explicitly for a colored label; the dependency graph stays intact.
+A shadow or glow status also uses a neutral derived surface, because Glaze does
+not allow a shadow or glow to be a mix target. Override the surface separately
+when needed.
 
 ### Configure Glaze adaptation
 
@@ -199,20 +200,36 @@ theme: {
     "accent-surface-subtle": {
       type: "mix", base: "surface", target: "accent-surface", value: [12, 20],
     },
-    shadow: {
-      type: "shadow", bg: "surface", fg: "text", intensity: [12, 24],
-      tuning: { alphaMax: 0.3 },
-    },
+    shadow: { type: "shadow", bg: "surface", intensity: [6, 0] },
   },
 },
 ```
 
-Palette roles accept Glaze's regular, mix, and shadow declarations. Mix and
-shadow references use the same graph as other roles. Native Glaze restrictions
-still apply, including the requirement for shadow backgrounds and foregrounds
-to reference non-shadow colors. `shadowTuning` exposes `saturationFactor`,
-`maxSaturation`, `lightnessFactor`, `lightnessBounds`, `minGapTarget`, `alphaMax`,
-and `bgHueBlend`; a role's own `tuning` takes precedence.
+Palette roles accept Glaze's regular, mix, shadow, and glow declarations. Mix,
+shadow, and glow references use the same graph as other roles. Native Glaze
+restrictions still apply, including the requirement for shadow and glow
+backgrounds and foregrounds to reference colors that are neither shadows nor
+glows.
+
+Without `fg`, a shadow's `intensity` is the exact number of tones the page
+darkens under it (a glow's, how many it lightens), with an optional
+high-contrast value. `fg` names the element that casts the shadow, not a
+contrast reference, and scales the step by that element's tone;
+`tuning: { objectInfluence: 0 }` turns this off. A step can't pass black: the
+default dark page sits about 9 tones above it, and the default dark
+high-contrast page is black, so give a shadow on the page `0` as its
+high-contrast value. A step that doesn't fit paints at full strength, and Glaze
+logs a "cannot reach" warning.
+
+The built-in `shadow` role steps 8 tones in light and dark, and is transparent
+in high contrast, where borders carry the edges. On the default surface, a
+`darkTone` whose dark end is below about 14 (including `false`), or a numeric
+`theme.contrastLevel` from about 25 to 99, leaves the dark page too close to
+black for the step, so the built-in shadow reaches full strength and Glaze
+warns. `shadowTuning` exposes Glaze's `objectInfluence`, `tint`, `reach`, and
+`hueBleed` for every shadow; a role's own `tuning` takes precedence, and a glow
+takes only its own `tuning`. See
+[Glaze shadows and glows](./upstream/glaze/docs/shadows-and-glows.mdx).
 
 ### Built-in palette inventory
 

package/docs/upstream/glaze/README.md

@@ -1,11 +1,11 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/glaze/v2.0.2/assets/glaze.svg" width="128" height="128" alt="Glaze logo">
+  <img src="https://raw.githubusercontent.com/tenphi/glaze/v3.0.0/assets/glaze.svg" width="128" height="128" alt="Glaze logo">
 </p>
 
 <h1 align="center">Glaze</h1>
 
 <p align="center">
-  OKHST-based color theme generator with WCAG and APCA contrast solving
+  <a href="https://github.com/tenphi/okhst">OKHST</a>-based color theme generator with WCAG and APCA contrast solving
 </p>
 
 <p align="center">
@@ -25,12 +25,13 @@ contrast floor.
 
 * **OKHST color space** — OKHSL with a contrast-shaped **tone** axis. Equal
   steps give equal WCAG contrast for neutrals and a useful approximation for
-  chromatic colors. See [OKHST in Glaze](docs/okhst.md) and the
+  chromatic colors. See [Tone and OKHST](docs/okhst.mdx) and the
   [full OKHST specification](https://github.com/tenphi/okhst).
 * **WCAG 2 + APCA contrast solving** — automatic tone adjustment to meet a WCAG ratio or APCA Lc floor
 * **Unified dark mode** — one tone space for light, dark, and high-contrast; dark is a single `100 − t` inversion, no fitted curve
 * **Mix colors** — blend two colors with OKHSL or sRGB interpolation, opaque or transparent, with optional contrast solving
-* **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
+* **Shadows and glows** — translucent overlays whose opacity is solved per surface, so `intensity` is an exact tone step wherever the surface has room for it (a step past black or white is pinned and warns), with object-aware strength
+* **HDR glows** — set `glowTuning.headroom` and a glow whose step passes white also gets an exact HDR value: extended sRGB `color(srgb …)` with channels past 1, plus a base and an exposure in DTCG for native apps, exported when you turn on `modes.hdr`. See [HDR glows](docs/hdr.mdx).
 * **Light + Dark + High-Contrast** — all schemes from one definition
 * **Manual contrast level** — put your normal palette on a `0–100` slider between itself and the high-contrast one; every level in between is solved, not approximated, and the high-contrast tier stays available on top
 * **Per-color hue override** — absolute or relative hue shifts within a theme
@@ -43,7 +44,7 @@ contrast floor.
 * **Import/Export** — serialize and restore themes, color tokens, and entire palettes as JSON
 * **Create from hex/RGB** — start from an existing brand color
 * **Zero dependencies** — pure math, runs anywhere (Node.js, browser, edge)
-* **Tree-shakeable ESM + CJS** — dual-format package
+* **ESM + CJS** — dual-format package
 * **TypeScript-first** — full type definitions included
 
 ## Installation
@@ -69,62 +70,69 @@ glaze.configure({
   modes: { dark: true, highContrast: true },
 });
 
-const defaultTheme = glaze(280, 80);
+const theme = glaze(280, 80);
 
-defaultTheme.colors({
+theme.colors({
   surface: { tone: 97, saturation: 0.15 },
   'surface-text': {
     base: 'surface',
     tone: '-1',
+    saturation: 0.4,
     contrast: { apca: ['content', 'body'] },
   },
   border: {
     base: 'surface',
     tone: ['-8', '-16'],
+    saturation: 0.2,
     inherit: false,
   },
-  'accent-surface': { tone: 52, mode: 'fixed' },
-  'accent-surface-text': {
-    base: 'accent-surface',
-    tone: '+1',
+  'accent-surface-text': { tone: 100, mode: 'fixed' },
+  'accent-surface': {
+    base: 'accent-surface-text',
+    tone: '-1',
     contrast: 'AA',
     mode: 'fixed',
   },
 });
 
-const dangerTheme = defaultTheme.extend({ hue: 23 });
-const palette = glaze.palette({ default: defaultTheme, danger: dangerTheme });
+const danger = theme.extend({ hue: 23 });
+const palette = glaze.palette({ default: theme, danger });
 
 const tokens = palette.tokens({
   prefix: { default: '', danger: 'danger-' },
 });
 // → {
 //   light: { surface: 'oklch(...)', 'danger-surface': 'oklch(...)', ... },
-//   dark: { surface: 'oklch(...)', 'danger-surface': 'oklch(...)', ... },
+//   dark: { ... },
 //   lightContrast: { ... },
 //   darkContrast: { ... },
 // }
 ```
 
+The accent fill is solved against its white label, not the reverse: the fill
+darkens until the pair meets `'AA'`, or `'AAA'` in high contrast, where a bare
+`'AA'` rises a tier.
+
 ## Concepts at a glance
 
 1. **A theme has one hue/saturation seed.** Create status themes with
    `extend()` so they inherit the same relationships while changing hue.
-2. **A color is a root or a dependency.** Roots use an absolute `tone` or
+2. **A color is a root or a dependent.** Roots use an absolute `tone` or
    `'max'`/`'min'`. Dependent colors name a `base` and may use a signed
    **tone delta** such as `'-8'` plus a `contrast` floor.
 3. **Tone is an authoring axis, not a contrast guarantee.** Equal tone deltas
    are exact WCAG steps for neutrals. Chromatic colors can drift in rendered
    luminance, so Glaze measures contrast floors against the resolved colors.
 4. **`contrast` is a floor.** A bare number or preset means WCAG;
-   `{ wcag }` and `{ apca }` select the metric explicitly. The solver preserves
-   the requested tone whenever it already passes.
+   `{ wcag }` and `{ apca }` select the metric explicitly. The solver keeps
+   the requested tone whenever it already clears the floor with a small
+   margin (1% over a WCAG ratio, 0.5 Lc over an APCA target).
 5. **Each color chooses its dark adaptation.** `mode: 'auto'` uses dark tone
    inversion (`100 - t`), `fixed` keeps the authored side of the tone scale,
    and `static` skips scheme adaptation.
 6. **Tone windows bound ordinary schemes.** `lightTone` and `darkTone`
-   configure the light/dark render ranges. High-contrast variants use the full
-   range. Values that accept `[normal, highContrast]` pairs can tighten
+   configure the light and dark tone windows. High-contrast variants use the
+   full range. Values that accept `[normal, highContrast]` pairs can tighten
    deliberately in HC.
 
 In Glaze, a **scheme variant** is one of `light`, `dark`, `lightContrast`, or
@@ -143,13 +151,25 @@ In Glaze, a **scheme variant** is one of `light`, `dark`, `lightContrast`, or
 
 ## Documentation
 
-* Explore the tone axis in the [interactive playground](https://glaze.tenphi.me/playground/).
-* Start with [the methodology](docs/methodology.md) to design a palette.
-* Use [migration and integration](docs/migration.md) to wire it into an
-  application or replace an existing color system.
-* Keep the [API reference](docs/api.md) nearby for every method and option.
-* Read [OKHST in Glaze](docs/okhst.md) for the product-level color model, or
-  the [full OKHST specification](https://github.com/tenphi/okhst) for its math.
+The full documentation, with live examples that follow your light / dark and
+contrast preferences, is at [glaze.tenphi.me](./README.md). The
+same pages live in [`docs/`](https://github.com/tenphi/glaze/blob/v3.0.0/docs):
+
+* [Getting started](docs/getting-started.mdx) — install, build a first theme,
+  and export it.
+* Concepts: [light, dark, and high contrast](docs/schemes.mdx),
+  [contrast solving](docs/contrast.mdx),
+  [shadows and glows](docs/shadows-and-glows.mdx),
+  [mixes and transparency](docs/mixes.mdx), and the color model under them,
+  [tone and OKHST](docs/okhst.mdx).
+* Guides: [designing a palette](docs/methodology.mdx),
+  [exporting and integration](docs/exporting.mdx), and
+  [migration and upgrading](docs/migration.md) (including Glaze 2 → 3).
+* The [API reference](docs/reference/index.md) for every method, option, and
+  type.
+* Explore the tone axis in the
+  [ramp explorer](./docs/okhst.mdx#ramp-explorer), or read the
+  [full OKHST specification](https://github.com/tenphi/okhst) for its math.
 * [`AGENTS.md`](https://github.com/tenphi/glaze/blob/main/AGENTS.md) — source-tree orientation for contributors.
 
 ## License