@tenphi/cookbook 0.21.1 → 0.21.4

package/dist/styling.d.ts

@@ -1,3 +1,3 @@
 
-import { Styles, defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
-export { type Styles, defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };
+import { Button, Styles, defineComponent, extendComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
+export { Button, type Styles, defineComponent, extendComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };

package/dist/styling.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
-export { defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };
+import { Button, defineComponent, extendComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
+export { Button, defineComponent, extendComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };

package/docs/architecture.md

@@ -47,8 +47,9 @@ Theme resolution has three deliberately separate layers:
    colors.
 2. The Glaze values, design tokens, typography presets, states, and units are
    registered directly with Tasty.
-3. Cookbook components use `tasty()` and the Tasty selector bridge styles DOM
-   owned by Astro, Pagefind, and rendered Markdown.
+3. Cookbook interface components use `tasty()` roots. Component-owned Tasty
+   bridges style generated Markdown and syntax markup. Search owns a styled
+   results root whose named descendants cover Pagefind's dynamic content.
 
 The palette owns color relationships. Components never choose raw light/dark
 colors, and shape tokens never contain palette logic. This keeps a palette
@@ -56,6 +57,50 @@ change, a density change, and a typography change independent. Astro runs
 Tasty in extract mode, so these runtime style calls become a shared static CSS
 asset during the build; no Tasty styling runtime ships to the browser.
 
+## Component ownership
+
+Each built-in component has an owning `components/<Name>.styles.js` module
+with its complete base style tree and named sub-elements. Its Astro markup
+imports that definition directly. Rendered roots use
+`defineComponent(name, options)` to apply partial `theme.styles`
+overrides before extraction. The published component names and sub-element
+lists define the public customization contract.
+
+Owned markup uses Tasty’s `data-element` identities; a named part usually needs
+no explicit `$` selector. Keep structural selectors for generated content and
+relationships between parts. Put conditions, including heading levels, in
+property state maps. Each actual part owns its complete styles; avoid broad
+selectors that also style parts with separate definitions.
+
+Use paired tokens for block margins and padding. Contextual spacing rules change
+only the relevant token; the owning shorthand consumes both edges. Spacing tokens
+are registered with `inherits: false` and reset in document foundations so nested
+content never inherits another element’s spacing.
+
+Use `extendComponent(name, base, options)` for derived roots. `Button`
+owns shared button defaults; `SearchButton` and `MobileMenuToggle` extend it
+with their own layout and named anatomy. Base theme overrides are inherited,
+then the descendant's styles and theme overrides take precedence. Keep shared
+bases configurable and document their names and complete sub-element lists.
+
+The page shell owns fonts, document defaults, heading presets, and root layout
+variables. These foundations initialize during every page render, including
+404 pages, independently of replaceable Header and Head components. Layout
+roots own frame positioning; the components inside them own their contents.
+
+`useGlobalStyles()` is reserved for document foundations and generated-content
+bridges, each using `resolveComponentStyles(name, baseStyles)`. MarkdownContent
+collects its prose, code, table, heading, alert, and Mermaid bridges during
+rendering. Generated prose retains its established selector scope and
+specificity so partial theme overrides and styled components inside Markdown
+continue to compose. CodeGroup collects its code and syntax bridges itself,
+including when rendered outside MarkdownContent.
+
+Optional browser behavior remains in `src/client/` and imports no styling
+modules. Custom elements attach behavior to the server-rendered markup.
+The ownership checks verify every public style name and sub-element, while
+consumer and browser tests exercise theme overrides and component replacements.
+
 ## Public graph API
 
 Renderer and tooling authors can work directly with `@tenphi/docs`:

package/docs/component-styles.md

@@ -6,9 +6,27 @@ For color roles and design tokens, start with the
 [theme overview](./theme-and-components.md). For your own components, see
 [Custom components](./custom-components.md).
 
+Owned markup uses Tasty's built-in `data-element` identities for its named parts.
+For example, Header's `Logo` styles target `data-element="Logo"` directly;
+no anatomy class or separate marker is required. A configured image logo owns
+its dimensions under `SiteLogo`.
+
+Heading levels are states of the same element. Customize them through a root
+property map such as `Heading: { textWrap: { "": "balance", ":is(h1)": "pretty" } }`.
+Markdown heading wrappers use `.level-h1` through `.level-h6` as root states.
+
+Block spacing uses `$margin-block-start` and `$margin-block-end` tokens. The
+owning `blockMargin` consumes both tokens, and a surrounding prose/layout rule
+changes only the start token. For example, `Callout: { "$margin-block-end": "3x" }`
+changes the end spacing while retaining Markdown's spacing before the callout.
+Document foundations reset these tokens on every element to prevent inheritance
+into nested content. For content-panel padding, use `MainContent.Panel`'s
+`$padding-block-start` and `$padding-block-end` tokens in the same way.
+
 ## Style customization
 
-Cookbook-owned interface elements are direct `tasty()` components. Supported
+Cookbook-owned interface elements use `defineComponent()` to create Tasty components
+and merge their named theme overrides. Shared bases use `extendComponent()`.
 Cookbook components and generated Markdown surfaces use Tasty style trees.
 Customize them by name under `theme.styles`; the configuration is resolved
 before CSS generation, so this is not a selector-based CSS override.
@@ -17,6 +35,12 @@ Cookbook merges your partial style object with the component's base styles
 before Tasty extracts CSS. The generated stylesheet contains the resolved
 style, so you can change an element without copying its full defaults.
 
+Each surface is registered by its owning component or generated-content bridge.
+Fonts and document defaults belong to the page shell, so replacing Header
+preserves the rest of the site's styling. Component-specific CSS is collected
+when its owner renders. See [Component ownership](./architecture.md#component-ownership)
+for the renderer authoring convention.
+
 Start with the area you want to change, then use the complete sub-element
 inventory below to find its exact anatomy:
 
@@ -59,17 +83,22 @@ Cookbook registers these Tasty state aliases for `theme.styles`, custom
 components, and recipes. Widths use CSS `rem` units; their pixel values depend
 on the browser's font-size settings.
 
-| State             | Condition                        | Typical use                                        |
-| ----------------- | -------------------------------- | -------------------------------------------------- |
-| `@compact`        | width ≤ 23rem                    | Hide optional header controls in very narrow space |
-| `@small`          | width ≤ 40rem                    | Stack compact grids                                |
-| `@shell-mobile`   | width ≤ 48rem                    | Switch the page shell to its narrow arrangement    |
-| `@shell-desktop`  | width > 48rem                    | Restore the wider shell arrangement                |
-| `@mobile`         | width < 50rem                    | Mobile navigation and component layouts            |
-| `@desktop`        | width ≥ 50rem                    | Desktop navigation and component layouts           |
-| `@medium-layout`  | 50rem ≤ width < 72rem            | Intermediate two-column layouts                    |
-| `@narrow-layout`  | width < 72rem                    | Hide or reposition the desktop table of contents   |
-| `@reduced-motion` | `prefers-reduced-motion: reduce` | Remove optional motion                             |
+| State             | Condition                                                  | Typical use                                        |
+| ----------------- | ---------------------------------------------------------- | -------------------------------------------------- |
+| `@compact`        | width ≤ 23rem                                              | Hide optional header controls in very narrow space |
+| `@small`          | width ≤ 40rem                                              | Stack compact grids                                |
+| `@shell-mobile`   | width ≤ 48rem                                              | Switch the page shell to its narrow arrangement    |
+| `@shell-desktop`  | width > 48rem                                              | Restore the wider shell arrangement                |
+| `@mobile`         | width < 50rem                                              | Mobile navigation and component layouts            |
+| `@desktop`        | width ≥ 50rem                                              | Desktop navigation and component layouts           |
+| `@medium-layout`  | 50rem ≤ width < 72rem                                      | Intermediate two-column layouts                    |
+| `@narrow-layout`  | width < 72rem                                              | Hide or reposition the desktop table of contents   |
+| `@popover-open`   | selected element is an open native popover                 | Use inside `@own(...)` for a descendant panel      |
+| `@reduced-motion` | `prefers-reduced-motion: reduce`                           | Remove optional motion                             |
+| `@light`          | explicit light theme, or system light when no theme is set | Match the site's effective light appearance        |
+| `@dark`           | explicit dark theme, or system dark when no theme is set   | Match the site's effective dark appearance         |
+| `@system-light`   | `prefers-color-scheme: light`                              | Read the operating system preference directly      |
+| `@system-dark`    | `prefers-color-scheme: dark`                               | Read the operating system preference directly      |
 
 The 48rem shell boundary, 50rem navigation boundary, and 72rem contents
 boundary serve different parts of the layout; their ranges intentionally
@@ -78,6 +107,12 @@ condition. Add your own aliases with `theme.states`; redefining a built-in
 alias also changes the renderer's responsive layout, so check the whole site
 when doing so.
 
+Use `@light` and `@dark` in component styles. They check the page root's
+`data-theme` attribute and use the system preference only when that attribute
+is absent. Document rules that style the root itself use `@system-light` and
+`@system-dark` within their automatic-theme branch. Keep scheme media queries
+in the shared state definitions instead of repeating them in style objects.
+
 In a generated site, run `npm run validate` (or the matching package manager's
 command) after editing `docs.config.ts`. It checks TypeScript theme properties,
 then runs Cookbook's preflight and production output checks. A misspelled
@@ -87,7 +122,34 @@ Provide only the root and named
 [sub-element](./upstream/tasty/docs/dsl.md#sub-element) properties you want to
 override. Cookbook deep-merges that partial style object into the complete
 base style object inside the renderer, following Tasty's
-[state-map merge semantics](./upstream/tasty/docs/dsl.md#extending-vs-replacing-state-maps):
+[state-map merge semantics](./upstream/tasty/docs/dsl.md#extending-vs-replacing-state-maps).
+
+Keep `$` selectors structural and put attribute or pseudo-class conditions in
+property state maps. Use `@own(...)` for a descendant's state and ordinary
+state keys for the component root. A sub-element cannot target its containing
+element: use root state maps for callout kinds, hover/active buttons, compact
+selectors, and syntax wrapping. Use Tasty element names such as `Primary > Search`
+instead of spelling out `[data-element="Primary"] > [data-element="Search"]`.
+A scalar override replaces the property's
+whole state map; use the matching state key without a default entry to change
+only that branch. `"": null` omits a declaration outside a condition. For
+conditional `display`, `"": null` is also supported, including styles with
+`flow` or `gap`.
+
+For a compact language selector, customize the root with
+`LanguageSelect: { border: { "[data-compact]": "4px solid #border" } }`.
+The former `Compact` hook is now a root state. Likewise, customize code wrapping
+with `SyntaxHighlight: { whiteSpace: { ".td-syntax-wrap": "pre-wrap" } }`.
+Syntax category sub-elements such as `Keyword` target descendant spans; use
+`SyntaxHighlight.color[".td-syntax-keyword"]` when customizing the containing
+code element itself.
+
+Cookbook temporarily retains selectors for pseudo-element states that Tasty
+cannot yet compile correctly and four empty legacy customization hooks whose
+conditional override scopes must remain compatible. Each has a narrow lint
+exception in its owning style module. Use state maps for new definitions.
+
+For example:
 
 ```ts
 theme: {
@@ -103,7 +165,7 @@ theme: {
     },
     TopNavigation: {
       Link: { preset: "body" },
-      CurrentLink: { color: "#accent-text" }
+      CurrentLink: { color: { '@own([aria-current="page"])': "#accent-text" } }
     },
     Sidebar: {
       LinkLabel: { whiteSpace: "normal" }
@@ -132,53 +194,54 @@ it stays complete when a surface changes.
 
 #### Page shell
 
-* `Document`: `All`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
-* `Layout`: `Islands`, `LockedPage`, `Light`, `Auto`
+* `Document`: `All`, `BlockSpacing`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
+* `Layout`: `Islands`
 * `PageFrame`: `MainFrame`, `SidebarFrame`, `Columns`
-* `MainPane`: `WithSidebars`
-* `MainContent`: `ContentSpacing`, `Container`, `Panel`, `FirstPanel`, `BodyPanel`
+* `MainPane`: None
+* `MainContent`: `ContentSpacing`, `Container`, `Panel`
 * `HeaderFrame`: None
-* `Heading`: `Level1`, `Level2`, `Level3`, `Level4`, `Level5`, `Level6`, `PageTitle`
+* `Heading`: None
 * `Banner`: `Link`
-* `SkipLink`: `Focus`
+* `SkipLink`: None
 
 #### Navigation and controls
 
-* `Header`: `Primary`, `TitleAndSearch`, `Title`, `LogoLink`, `Logo`, `SiteTitle`, `Search`, `SearchElement`, `Tools`, `ToolItem`, `Social`, `MobileTheme`, `MobileLanguage`
+* `Header`: `Primary`, `Title`, `LogoLink`, `Logo`, `SiteTitle`, `Search`, `SearchElement`, `Tools`, `Social`, `MobileTheme`, `MobileLanguage`
 * `HeaderLinks`: `Desktop`, `DesktopLink`, `Link`, `HoverLink`, `PrimaryLink`, `HoverPrimaryLink`, `Trigger`, `HoverTrigger`, `Panel`, `OpenPanel`, `PanelNavigation`, `PanelLink`, `FirstPanelLink`, `Close`, `HoverClose`
-* `SearchButton`: `PendingShortcut`, `Label`, `Shortcut`, `Hover`, `Active`, `NativeIcon`, `Icon`
-* `Sidebar`: `Backdrop`, `OpenBackdrop`, `MobileHeading`, `HomeLink`, `HomeLogo`, `HomeLabel`, `Close`, `HoverClose`, `CloseIcon`, `CurrentLink`, `OpenPane`, `EnteredPane`, `Content`, `Tree`, `List`, `Item`, `TopLevelSpacing`, `GroupSpacing`, `NestedItem`, `SectionHeading`, `Control`, `Summary`, `GroupLabel`, `GroupLabelText`, `Link`, `LinkLabel`, `InteractiveControl`, `SummaryMarker`, `Caret`, `ExpandedCaret`, `LinkedSummary`, `GroupLink`, `LinkedSectionHeading`, `SectionLink`, `Badge`, `TopLevelLink`
-* `MobileMenuToggle`: `Control`, `Icon`, `Section`, `Page`, `HoverControl`, `ActiveControl`
+* `SearchButton`: `PendingShortcut`, `Label`, `Shortcut`, `NativeIcon`, `Icon`
+* `Button`: None
+* `Sidebar`: `Backdrop`, `OpenBackdrop`, `MobileHeading`, `HomeLink`, `HomeLogo`, `HomeLabel`, `Close`, `HoverClose`, `CloseIcon`, `CurrentLink`, `Content`, `Tree`, `List`, `Item`, `TopLevelSpacing`, `GroupSpacing`, `NestedItem`, `SectionHeading`, `Control`, `Summary`, `GroupLabel`, `GroupLabelText`, `Link`, `LinkLabel`, `InteractiveControl`, `SummaryMarker`, `Caret`, `ExpandedCaret`, `LinkedSummary`, `GroupLink`, `LinkedSectionHeading`, `SectionLink`, `Badge`, `TopLevelLink`
+* `MobileMenuToggle`: `Icon`, `Section`, `Page`
 * `MobileNavigationTabs`: `Trigger`, `Marker`, `Caret`, `ExpandedCaret`, `Label`, `List`, `Item`, `Link`, `HoverLink`, `CurrentLink`
 * `MobileMenuFooter`: `Social`
 * `TopNavigation`: `Scrollbar`, `Link`, `HoverLink`, `CurrentLink`, `ActiveIndicator`
-* `TableOfContentsLayout`: `WithMobile`, `Content`
+* `TableOfContentsLayout`: `Content`
 * `TableOfContents`: `Heading`, `List`, `Item`, `Link`, `LinkLabel`, `HoverLink`, `CurrentLink`
 * `MobileTableOfContents`: `Summary`, `List`, `NestedList`, `Item`, `Link`, `HoverLink`, `Focus`
 * `Pagination`: `Link`, `PreviousLink`, `NextLink`, `NextIcon`, `NextLabel`, `HoverLink`, `ActiveLink`, `Title`, `LoneNextLink`, `Icon`, `PreviousIconRtl`, `NextIconRtl`
 * `VersionSwitcher`: `Trigger`, `HoverTrigger`, `TriggerLabel`, `Caret`, `Panel`, `OpenPanel`, `PanelTitle`, `Options`, `Link`, `HoverLink`, `CurrentLink`, `Checkmark`, `SelectedCheckmark`
-* `LanguageSelect`: `Compact`, `Trigger`, `HoverTrigger`, `ActiveTrigger`, `LabelIcon`, `TriggerLabel`, `Caret`, `CompactTrigger`, `CompactLabel`, `CompactCaret`, `Label`, `HoverLabel`, `Select`, `CompactSelect`, `CompactLabelIcon`, `SidebarTrigger`, `Panel`, `SidebarPanel`, `OpenPanel`, `PanelTitle`, `Options`, `Option`, `HoverOption`, `CurrentOption`, `Fallback`, `Checkmark`, `SelectedCheckmark`
+* `LanguageSelect`: `Trigger`, `HoverTrigger`, `ActiveTrigger`, `LabelIcon`, `TriggerLabel`, `Caret`, `CompactTrigger`, `CompactLabel`, `CompactCaret`, `Label`, `HoverLabel`, `Select`, `CompactSelect`, `CompactLabelIcon`, `SidebarTrigger`, `Panel`, `SidebarPanel`, `OpenPanel`, `PanelTitle`, `Options`, `Option`, `HoverOption`, `CurrentOption`, `Fallback`, `Checkmark`, `SelectedCheckmark`
 * `SocialIcons`: `Link`, `HoverLink`, `Icon`
 * `ThemeSelect`: `Trigger`, `HoverTrigger`, `ActiveTrigger`, `Icon`, `Panel`, `OpenPanel`, `Section`, `SectionSpacing`, `SectionLabel`, `Option`, `HoverOption`, `CheckedOption`, `FocusedOption`, `Input`, `OptionIcon`, `Checkmark`, `SelectedCheckmark`
 
 #### Rendered content
 
 * `Markdown`: `Block`, `BlockSpacing`, `HeadingSpacing`, `List`, `CompactItem`, `ListItem`, `DefinitionTerm`, `DefinitionDescription`, `Link`, `HoverLink`, `Quote`, `Rule`, `Details`, `HoverDetails`, `Summary`, `OpenSummary`, `SummaryMarker`, `SummaryIcon`, `OpenSummaryIcon`, `Code`
-* `MarkdownHeading`: `Heading`, `Heading1`, `Heading2`, `Heading3`, `Heading4`, `Heading5`, `Heading6`, `Link`, `RevealedLink`, `HoverLink`, `LinkIcon`, `CopiedLink`, `CopiedLinkIcon`, `CopiedIcon`
+* `MarkdownHeading`: `Heading`, `Link`, `RevealedLink`, `HoverLink`, `LinkIcon`, `CopiedLink`, `CopiedLinkIcon`, `CopiedIcon`
 * `MarkdownCodeBlock`: `Pre`, `CopyButton`, `HoverCopyButton`, `CopiedButton`, `CopyIcon`, `CopiedIcon`, `Code`, `Diff`, `DiffCode`, `DiffLine`, `EmptyDiffLine`, `InsertedLine`, `DeletedLine`
 * `MarkdownInlineCode`: None
 * `MarkdownTable`: `Table`, `Cell`, `LastBodyRowCell`, `HeaderCell`, `Scroll`
-* `MarkdownAlert`: `Note`, `Tip`, `Caution`, `Danger`, `Title`, `FirstContent`
-* `SyntaxHighlight`: `Scroll`, `Wrap`, `Marker`, `Comment`, `Punctuation`, `Keyword`, `String`, `Token`, `Property`, `Number`, `Function`, `Value`, `Operator`, `Text`, `Bg`, `Inserted`, `Deleted`, `Italic`, `Strong`, `Underline`
+* `MarkdownAlert`: `Title`, `FirstContent`
+* `SyntaxHighlight`: `Marker`, `Comment`, `Punctuation`, `Keyword`, `String`, `Token`, `Property`, `Number`, `Function`, `Value`, `Operator`, `Text`, `Bg`, `Inserted`, `Deleted`, `Italic`, `Strong`, `Underline`
 * `Mermaid`: `Diagram`, `Text`, `MonoText`
 * `MermaidSource`: None
 
 #### Authoring components
 
 * `Card`: `Heading2`, `Heading3`, `Paragraph`
-* `Callout`: `Title`, `Body`, `Tip`, `Caution`, `Danger`
+* `Callout`: `Title`, `Body`
 * `CodeGroup`: `Caption`, `Pre`, `Code`
-* `Tab`: `Heading`, `Hidden`, `HiddenHeading`
+* `Tab`: `Heading`, `HiddenHeading`
 * `Tabs`: `List`, `Button`, `SelectedButton`, `FocusedButton`
 * `Steps`: `Item`, `Marker`
 * `Hero`: `Visual`, `DarkVisual`, `LightVisual`, `Stack`, `Copy`, `Title`, `Tagline`, `Actions`, `Action`, `HoverAction`, `PrimaryAction`, `SecondaryAction`, `MinimalAction`, `ActionIcon`
@@ -186,7 +249,7 @@ it stays complete when a surface changes.
 * `SiteLogo`: `Image`, `Light`, `Dark`
 * `Logo`: `Svg`, `Mark`
 * `PageActions`: `Control`, `Hover`, `Focus`, `Pending`, `Status`
-* `Footer`: `Meta`, `LoneMetaItem`, `MetaLink`, `HoverMetaLink`, `Credit`, `CreditLink`, `HoverCreditLink`
+* `Footer`: `Meta`, `MetaLink`, `MetaUpdated`, `Credit`, `CreditLink`
 * `PackageVersion`: None
 
 #### Search
@@ -232,7 +295,7 @@ same.
 
 Register custom names and their partial Tasty objects in `theme.customStyles`.
 Built-in names belong in `theme.styles` and reject misspelled sub-elements.
-The name must match the string passed to `defineComponent()` or
+The name must match the string passed to `defineComponent()`, `extendComponent()`, or
 `resolveComponentStyles()`. A production
 build warns when a configured custom name has no matching component style
 resolver.

package/docs/configuration.md

@@ -441,8 +441,8 @@ theme: {
 ```
 
 The default brand is `okhsl(266 68% 48%)`, a blue with 68% saturation.
-Controls use an `8px` radius and cards use `16px`. Onest is the default body
-and heading family; JetBrains Mono is used for code. `theme.fonts` loads Google
+Controls use an `8px` radius and cards use `16px`. Onest Variable is the default body
+and heading family; JetBrains Mono Variable is used for code. `theme.fonts` loads Google
 families by name or local files from `public/`. See
 [Fonts and typography](./fonts-and-typography.md) for both flows.
 
@@ -662,10 +662,31 @@ translations: {
 
 `navigation.<configured label>` translates named tabs and navigation groups.
 Automatically generated links use the title from the translated page.
-Cookbook message keys are `appearance`, `colorScheme`, `contrast`,
-`normalContrast`, `highContrast`, `auto`, `closeNavigation`, `primary`, `sections`,
-`chooseSection`, `headerLinks`, `more`, `closeMore`, `moreLinks`, `versions`,
-`documentationVersion`, `documentationVersions`, `version`, `home`,
-`generatedWith`, `viewSource`, `copyCode`, `codeCopied`, `codeCopyError`,
-`copyHeading`, `linkCopied`, `linkCopyError`, `notFound`, `notFoundDescription`,
-and `fallback`. Preserve `{heading}` in the `copyHeading` message.
+The supported keys below keep independent overrides, including similar labels:
+`auto` controls contrast, while `themeSelect.auto` controls color scheme;
+`search.label` labels the search control, while `pagefind.search` supplies the
+search input prompt. No migration or key renaming is needed.
+
+| Keys                                                                                                                | Controls or feedback                                                            |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `copyPage`, `viewMarkdown`, `pageCopied`, `pageCopyError`                                                           | Page Markdown actions and copy status.                                          |
+| `draftTitle`, `draftNotice`                                                                                         | Draft-page notice.                                                              |
+| `searchError`                                                                                                       | Search loading failure.                                                         |
+| `appearance`, `colorScheme`, `contrast`, `normalContrast`, `highContrast`, `auto`                                   | Appearance and contrast controls.                                               |
+| `closeNavigation`, `primary`, `sections`, `chooseSection`                                                           | Primary and mobile navigation.                                                  |
+| `headerLinks`, `more`, `closeMore`, `moreLinks`                                                                     | Header links and overflow menu.                                                 |
+| `versions`, `documentationVersion`, `documentationVersions`, `version`                                              | Version selection and package labels.                                           |
+| `home`, `generatedWith`, `viewSource`                                                                               | Home, footer credit and preview source.                                         |
+| `copyCode`, `codeCopied`, `codeCopyError`                                                                           | Code copy action and status.                                                    |
+| `copyHeading`, `linkCopied`, `linkCopyError`                                                                        | Heading link action and status. Preserve `{heading}` in `copyHeading`.          |
+| `notFound`, `notFoundDescription`, `fallback`                                                                       | Missing-page and language fallback messages.                                    |
+| `sidebarNav.accessibleLabel`, `menuButton.accessibleLabel`                                                          | Sidebar navigation and menu accessible names.                                   |
+| `tableOfContents.onThisPage`, `languageSelect.accessibleLabel`                                                      | Contents heading and language selector.                                         |
+| `themeSelect.light`, `themeSelect.dark`, `themeSelect.auto`                                                         | Color-scheme options.                                                           |
+| `search.label`, `search.ctrlKey`, `search.cancelLabel`, `search.devWarning`                                         | Search control, shortcut, close action and development notice.                  |
+| `page.nextLink`, `page.previousLink`, `page.editLink`, `page.lastUpdated`, `page.skipToContent`                     | Pagination, edit/update labels and skip link.                                   |
+| `pagefind.search`, `pagefind.clear_search`, `pagefind.zero_results`, `pagefind.many_results`, `pagefind.one_result` | Search input, clearing and result counts. Preserve `[COUNT]` in count messages. |
+
+Custom component message keys are also preserved. Missing custom keys passed to
+`Astro.locals.t(key)` return the key itself. Changing an override does not alter
+other message keys, even when their default text is the same.

package/docs/custom-components.md

@@ -2,7 +2,6 @@
 title: Custom components
 description: Style your Astro and MDX components with Tasty and validate their tokens and parts.
 ---
-
 Use this guide after [theme configuration](./theme-and-components.md) when you
 need markup beyond Cookbook's built-in surfaces. For ordinary visual changes,
 consult the [component styles](./component-styles.md) reference first.
@@ -17,6 +16,8 @@ responsive states. The renderer package also exposes them from
 | Export                   | Purpose                                                                            |
 | ------------------------ | ---------------------------------------------------------------------------------- |
 | `defineComponent`        | Create a named Tasty component with its `theme.customStyles[name]` overrides.      |
+| `extendComponent`        | Extend an existing Tasty component with a new name and its own theme overrides.    |
+| `Button`                 | Shared button foundation used by Cookbook controls and custom button components.   |
 | `tasty`                  | Use Tasty directly without binding a component to `theme.customStyles`.            |
 | `useGlobalStyles`        | Collect a global Tasty style tree while rendering a page.                          |
 | `resolveComponentStyles` | Merge `theme.customStyles[name]` into a complete base style tree for global rules. |
@@ -235,6 +236,49 @@ that does not need a configuration name. To define a named component around
 an existing React component that forwards `className`, pass it as `as` in the options. Use `className`
 when passing a class to a Tasty component from Astro.
 
+### Extending a component
+
+Use `extendComponent(name, base, options)` to inherit an existing Tasty
+component's styles, props, variants, and compound parts:
+
+```ts
+import { Button, extendComponent } from "@tenphi/cookbook/styling";
+
+export const ProjectButton = extendComponent("ProjectButton", Button, {
+  type: "button",
+  styles: {
+    padding: "1x 2x",
+    radius: "$radius",
+    fill: "#surface",
+    Hover: { $: "&:hover", fill: "#surface-2-hover" },
+  },
+});
+
+export const CompactButton = extendComponent("CompactButton", ProjectButton, {
+  styles: { padding: "0.5x 1x" },
+});
+```
+
+`theme.styles.Button` customizes the shared foundation, including Cookbook's
+search and mobile-menu buttons. `theme.customStyles.ProjectButton` and
+`CompactButton` customize each derived component independently. `Button` has
+no named sub-elements; this example adds `Hover` to both descendants.
+
+The merge order is the base component's configured styles and selected variant,
+the extension's styles, its named theme override, and styles passed while
+rendering. Tasty merges named sub-elements and state maps using its usual
+[extending and replacing rules](./upstream/tasty/docs/dsl.md#extending-vs-replacing-state-maps).
+Changing a descendant never mutates its base or siblings. If a base exposes
+parts such as `Button.Label`, the descendant exposes those same components.
+
+Extension options accept styles and default values for existing props. Define
+new `elements`, `variants`, `styleProps`, `modProps`, `tokenProps`, or an `as`
+type on the original factory; Tasty's wrapping API does not install new factory
+settings. Existing required props remain required in the derived component's
+type. To compose reusable style fragments without a component base, use
+`mergeStyles(baseStyles, extensionStyles)`; a shallow spread replaces entire
+nested sub-elements and state maps.
+
 ### Global style trees
 
 For markup you do not render through a Tasty component, call
@@ -261,7 +305,7 @@ useGlobalStyles(
 <aside class="project-note"><strong>Note</strong><slot /></aside>
 ```
 
-`defineComponent` and `resolveComponentStyles` read the same `theme.customStyles`
+`defineComponent`, `extendComponent`, and `resolveComponentStyles` read the same `theme.customStyles`
 configuration; user configuration contains only the properties to change. Each custom style name must match a call to one of these helpers.
 
 ## Linting custom styles
@@ -283,7 +327,7 @@ export default {
 Renderer-only consumers can use `extends: "@tenphi/renderer"` instead.
 The preset registers both Cookbook styling import paths, its built-in tokens,
 units, responsive states, and typography presets. It also describes
-`defineComponent`, `resolveComponentStyles`, and `mergeStyles`, so their inline
+`defineComponent`, `extendComponent`, `resolveComponentStyles`, and `mergeStyles`, so their inline
 style objects, variants, and named sub-elements receive the same checks as
 `tasty()` calls. Partial overrides passed to `mergeStyles` may omit default state
 values and retain the plugin's safeguards against fixes that replace base styles.

package/docs/fonts-and-typography.md

@@ -8,10 +8,28 @@ named presets to the rendered site.
 
 ## Typography presets
 
-The built-in [typography presets](./upstream/tasty/docs/styles.md#preset) are
+The base [typography presets](./upstream/tasty/docs/styles.md#preset) are
 `body`, `heading`, `h1` through `h6`, `navigation`, `small`, and `code`. Onest
-is self-hosted and used for body and heading text by default; JetBrains Mono is
-self-hosted for code.
+Variable is self-hosted and used for body and heading text by default, with a
+continuous weight range from `100` to `900`. This supports intermediate preset
+weights such as `450` for navigation and `610` for headings. JetBrains Mono
+Variable is self-hosted for code with weights from `100` to `800`.
+
+Both default fonts bundle their Latin subset and require no Google Fonts
+requests at build time or in the browser. For other character sets, configure
+`theme.fonts` with a Google family or local files as described below.
+
+Specialized roles preserve the component sizes while sharing their base typography:
+
+| Preset         | Used for          | Base typography                                     |
+| -------------- | ----------------- | --------------------------------------------------- |
+| `hero-title`   | Hero heading      | `h1`, with a larger responsive size                 |
+| `hero-tagline` | Hero description  | `body`, with a responsive size and 1.55 line height |
+| `prose`        | Markdown content  | `body`, at 1.025rem                                 |
+| `inline-code`  | Code within prose | `code`, at 0.875em                                  |
+
+Customize these through `theme.presets` as well. Changes to the base font family,
+weight, tracking, and other shared fields continue to flow into the derived roles.
 
 ### Change font families
 

package/docs/migration.md

@@ -54,7 +54,13 @@ Configure `theme.tokens` with `$name` keys, such as `$radius`. The old `--name`
 configuration keys now fail validation; the emitted CSS custom properties
 still use `--name`.
 
-Custom styles no longer target `data-tasty-anatomy` attributes automatically.
+Built-in markup now uses Tasty’s `data-element` identities instead of
+`data-tasty-anatomy`. Custom styles resolve through each owning definition.
+Heading levels move from `Heading.Level1`–`Level6` to root property state maps
+(`:is(h1)`–`:is(h6)`); Markdown wrappers use `.level-h1`–`.level-h6`.
+Panel first/second-child padding moves into `MainContent.Panel` token state maps.
+Header’s shared title/search defaults live on `Title` and `Search`; Footer’s
+only-child and hover states live on `MetaLink`, `MetaUpdated`, and `CreditLink`.
 For a custom component, use `defineComponent(name, options)`. For custom global
 rules, pass `resolveComponentStyles(name, baseStyles)` to `useGlobalStyles()`.
 Both merge `theme.customStyles[name]` into the complete base styles during

package/docs/upstream/manifest.json

@@ -1,10 +1,10 @@
 [
   {
     "name": "@tenphi/tasty",
-    "version": "3.8.0",
+    "version": "3.9.6",
     "license": "MIT",
     "repository": "https://github.com/tenphi/tasty",
-    "ref": "v3.8.0",
+    "ref": "v3.9.6",
     "directory": "upstream/tasty"
   },
   {

package/docs/upstream/tasty/README.md

@@ -1,18 +1,18 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.8.0/assets/tasty.svg" width="128" height="128" alt="Tasty logo">
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.6/assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
 </p>
 
 <h1 align="center">Tasty</h1>
 
 <p align="center">
-  <strong>CSS-in-JS for React design systems.</strong><br>
+  <strong>CSS-in-JS for React design systems.</strong><br />
   Build components whose styles don’t fight.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@tenphi/tasty"><img src="https://img.shields.io/npm/v/@tenphi/tasty.svg" alt="npm version"></a>
-  <a href="https://github.com/tenphi/tasty/actions/workflows/ci.yml"><img src="https://github.com/tenphi/tasty/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
-  <a href="https://github.com/tenphi/tasty/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tenphi/tasty" alt="license"></a>
+  <a href="https://www.npmjs.com/package/@tenphi/tasty"><img src="https://img.shields.io/npm/v/@tenphi/tasty.svg" alt="npm version" /></a>
+  <a href="https://github.com/tenphi/tasty/actions/workflows/ci.yml"><img src="https://github.com/tenphi/tasty/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="https://github.com/tenphi/tasty/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tenphi/tasty" alt="license" /></a>
 </p>
 
 ***
@@ -615,7 +615,7 @@ const tokens = theme.tasty(); // Ready-to-use Tasty tokens
 Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, and related APIs.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.8.0/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example">
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.6/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
 </p>
 
 ## Built with Tasty

package/docs/upstream/tasty/docs/ai-agents.md

@@ -22,6 +22,12 @@ tastyStatic('.card', { … });                                              // b
 - Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
 - Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
   ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+- Keep JavaScript identifiers, calls, computed keys, and interpolated templates
+  out of style values. Use token references inside strings for values supplied
+  at runtime. Spell out style properties rather than spreading objects; if a
+  runtime spread is unavoidable, add a
+  `// eslint-disable-next-line tasty/no-style-spread -- reason` comment directly
+  above it. `tastyStatic()` cannot use spreads.
 
 ## 2. Property names
 
@@ -128,7 +134,19 @@ Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `row
 
 Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
 
-❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill'`
+
+Omit the duration to use `$fill-transition` with `$transition` as fallback, or
+use a duration token explicitly (`transition: 'fill $transition'`). Avoid raw
+time values in duration slots. An explicit zero can be useful to disable motion.
+
+Use `transition` when defining a complete transition, and the native CSS
+`animation` shorthand when defining a complete animation. Tasty accepts
+`animation` directly and tracks local keyframes referenced by it; no special
+animation handler is needed. Use duration tokens in either form. Keep
+`transitionDuration`, `animationDuration`, and other motion longhands when a
+state or extension changes only one part of an existing effect. A shorthand
+resets omitted parts, including an animation's timeline and range.
 
 ## 4. State maps
 
@@ -155,7 +173,8 @@ Rules:
 3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be _unknown_ (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
 4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
 5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
-6. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
+6. **Write keys Tasty can fully read.** Names start with a letter (a single letter is fine: `x` → `[data-x]`); join states with an operator (`hovered & focused`, not `hovered focused`); no space between `@media` and `(`. Tasty warns (`INVALID_STATE_KEY`) and skips what it cannot read.
+7. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
 
 ```jsx
 color: { '': '#text', hovered: '#accent', disabled: '#text.40' }

package/docs/upstream/tasty/docs/debug.md

@@ -6,9 +6,7 @@ Runtime CSS inspection and diagnostics for the Tasty styling system. Inspect inj
 
 ## Overview
 
-`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use but can be manually installed in production for debugging.
-
-In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, install it manually when needed.
+`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use and can be installed on `window` explicitly when needed.
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
@@ -19,7 +17,6 @@ All methods **log to the console by default**. Pass `{ raw: true }` to suppress
 ## Quick Start
 
 ```typescript
-// Auto-installed in dev mode. Otherwise:
 import { tastyDebug } from '@tenphi/tasty';
 tastyDebug.install();
 
@@ -277,7 +274,7 @@ tastyDebug.help();
 
 ### `install(): void`
 
-Attaches `tastyDebug` to `window.tastyDebug`. Called automatically in development mode.
+Attaches `tastyDebug` to `window.tastyDebug`.
 
 ```typescript
 import { tastyDebug } from '@tenphi/tasty';