Improve plugin capabilities.

Author: koculu

frontend/purestack.studio/guides/extending/plugins.mdx

@@ -109,7 +109,7 @@ The stylesheet provider initializes before component factories, then all config
 
 Metadata defaults compose through `headConfig({ site, pageInfo })` in plugin order, before explicit frontmatter `head` overrides and before head markup is rendered. It returns `BasicHeadConfig` or a promise. The SEO plugin uses this contribution for Open Graph, Twitter, canonical URLs, and translated alternate links; page templates receive the completed `headConfig`. Basic titles, descriptions, explicit head settings, and `index: false` enforcement remain in core.
 
-Auth hints, consent, and analytics are independent plugins in `ts-page-scripts`. The analytics plugin registers automatic GA4 consent services during `onConfigResolved`, before later config hooks and rendering. Omitting it removes automatic registration and direct tracking scripts. Explicitly configured consent services remain available. Analytics never bypasses enabled consent when the consent runtime plugin is omitted.
+Auth hints, consent, and analytics are independent plugins in `ts-page-scripts`. The analytics plugin contributes automatic GA4 consent services during configuration resolution, before any factory or lifecycle hook runs. Omitting it removes automatic registration and direct tracking scripts. Explicitly configured consent services remain available. Analytics never bypasses enabled consent when the consent runtime plugin is omitted.
 
 To choose the standard integrations yourself, disable the automatic set and list the plugins you want. The factories are exported from `purestack`, `@purestack/ts-ssg`, and their individual packages:
 
@@ -130,6 +130,51 @@ The highlighting plugin selects the configured backend. Configure native backend
 
 The Pagefind plugin supplies a `search` provider. To use another engine, replace `purestack:pagefind` or disable the default set and install your own provider. The builder supplies excluded output paths and the rendered-page list for lazy requests, and manages invalidation on edits and deletions. Sitemap and robots generation remain built in.
 
+## Configure a plugin
+
+Plugins contribute configuration through `config.resolve({ config, input, file })` and `config.finalize({ config, input, file })`. Both are optional and synchronous. Each returns an object to merge into the config; do not mutate the inputs. All resolvers run first in plugin order, applying configuration overrides. Then all finalizers run in plugin order, deriving dependent settings from the completed overrides. Finalizers should derive settings rather than change resolver inputs. Both phases finish before highlighters, Markdown processors, styles, search providers, components, and templates initialize. The analytics plugin finalizes its automatic GA4 service here, so later site resolvers can enable analytics, change its ID or category, or provide a manual service. The existing `onConfigResolved` hook still runs after factories, so it can customize initialized components and templates. Publishing applies its output-directory and minification overrides after configuration composition.
+
+Custom site settings belong under `extensions` in `siteConfig.json`. File values merge with programmatic input, which takes precedence. The standard JSON schema allows plugin namespaces here while continuing to reject unknown top-level fields. Each plugin owns validation, defaults, and normalization for its namespace. Other namespaces are preserved.
+
+```json
+{ "extensions": { "brand": { "label": "Acme" } } }
+```
+
+Use TypeScript module augmentation for typed settings:
+
+```ts
+import { definePlugin } from 'purestack'
+
+declare module '@purestack/ts-common' {
+  interface SiteExtensions {
+    brand?: { label: string }
+  }
+}
+
+export const brandPlugin = definePlugin({
+  name: 'brand',
+  config: {
+    resolve({ config }) {
+      const brand = config.extensions.brand
+      if (brand !== undefined &&
+          (brand === null || typeof brand !== 'object' ||
+           typeof brand.label !== 'string')) {
+        throw new Error('extensions.brand requires a string label.')
+      }
+      return { extensions: { brand: { label: brand?.label ?? 'Docs' } } }
+    },
+  },
+  components(config) {
+    // config.extensions.brand contains the normalized settings here.
+    return {}
+  },
+})
+```
+
+Raw `resolveSiteConfig(input)` resolves core settings and extension input. CLI and programmatic builds additionally compose their selected plugins' configuration contributions. Configuration contributions are synchronous and may run whenever a project configuration is resolved; keep file writes and other side effects in lifecycle hooks.
+
+Builder style state is isolated across asynchronous operations, including concurrent sites. Its owned theme options remain linked to `context.config.style.theme`, so in-place config-hook changes and `themes.setOptions` update page colors, CSS, and generated favicons consistently. Head, metadata, template, Markdown, provider, and lifecycle errors identify their owning plugin and preserve the original cause. Markdown wrappers preserve unified presets, duplicate-plugin option merging, and callback transforms.
+
 ## How the config loads
 
 - **Where it lives.** The CLI looks for `purestack.config.ts` in the folder passed to `--content`. It must default-export `defineConfig({ plugins: [...] })`.
@@ -541,6 +586,7 @@ Every field except `name` is optional.
 | `name` | `string`, unique among the site's plugins |
 | `defaults` | `boolean`; makes component and template contributions overridable defaults without changing initialization order |
 | `skins` | Skins by name, each `{ create(): ThemeSkinPair }` |
+| `config` | `{ resolve?: SiteConfigResolver, finalize?: SiteConfigResolver }`; overrides, then derived settings, before factories |
 | `components` | `(config) => ({ [name]: component })` |
 | `templates` | Templates by name, each `(input) => TSNode<'html'>` |
 | `head` | `(input) => TSNode<'head'>`, or a promise; composes head markup before the page template |

packages/ts-common/src/index.ts

@@ -64,7 +64,11 @@ export type {
   PreviewConfig,
   RobotsConfig,
   SiteConfig,
+  SiteConfigContributions,
   SiteConfigInput,
+  SiteConfigResolution,
+  SiteConfigResolver,
+  SiteExtensions,
   SiteHtmlConfig,
   SiteMdxConfig,
   SitemapConfig,

packages/ts-common/src/site-config-types.ts

@@ -9,6 +9,8 @@ import type { SiteLogoConfig } from './logo-types'
 import type { NavigationConfig } from './navMenu-types'
 
 export interface SiteConfig {
+  /** Plugin-owned settings, normalized by their configuration contributions. */
+  extensions: SiteExtensions
   rootDir: string
   contentDir: string
   outDir: string
@@ -33,6 +35,11 @@ export interface SiteConfig {
   mdx: SiteMdxConfig
 }
 
+/** Plugins may augment this interface with optional, typed namespaces. */
+export interface SiteExtensions {
+  [plugin: string]: unknown
+}
+
 export interface DocLayoutConfig {
   /** CSS length reserved above desktop navigation and TOC sidebars. */
   sidebarTop: string
@@ -147,3 +154,20 @@ export type SiteStyleConfigInput = DeepPartial<
 export type SiteConfigInput = DeepPartial<Omit<SiteConfig, 'style'>> & {
   style?: SiteStyleConfigInput
 }
+
+/** Inputs for a pure configuration contribution, before build factories run. */
+export interface SiteConfigResolution {
+  config: SiteConfig
+  input: SiteConfigInput
+  file: SiteConfigInput
+}
+
+export type SiteConfigResolver = (
+  source: SiteConfigResolution,
+) => DeepPartial<SiteConfig>
+
+/** All overrides resolve before any plugin derives dependent settings. */
+export interface SiteConfigContributions {
+  resolve?: SiteConfigResolver
+  finalize?: SiteConfigResolver
+}

packages/ts-common/src/site-styles.ts

@@ -7,7 +7,7 @@ export interface WriteStylesResult {
   signature: string
 }
 
-/** A plugin's stylesheet output, initialized before component factories. */
+/** A site's stylesheet output, initialized after config contributions and before component factories. */
 export interface SiteStyles {
   readonly revision: number
   links(cacheKey?: string): ThemeStylesheetLink[]

packages/ts-css/src/baseStyle.ts

@@ -6,13 +6,24 @@ import { hyphenizeCss } from './hyphenize'
 
 export abstract class RootStyle {
   static nextId = 1
-  static revision = 0
+  #revision = { value: 0 }
+  /** Changes anywhere in this style tree, independent of other trees. */
+  get revision() {
+    return this.#revision.value
+  }
+  protected changed() {
+    this.#revision.value += 1
+  }
+  protected shareRevision(child: RootStyle) {
+    this.#revision.value += child.#revision.value
+    child.#revision = this.#revision
+  }
   id: number
   selector: string
   constructor(selector?: string) {
     this.id = BaseStyle.nextId++
     this.selector = selector ?? ''
-    RootStyle.revision += 1
+    this.changed()
   }
   abstract toCSS(): string
 }
@@ -23,15 +34,19 @@ export class BaseStyle<T extends RootStyle> extends RootStyle {
   #createT: (selector?: string) => T
   constructor(createT: (selector?: string) => T, selector?: string) {
     super(selector)
-    this.#createT = createT
+    this.#createT = (selector) => {
+      const child = createT(selector)
+      this.shareRevision(child)
+      return child
+    }
   }
 
   set(key: string, value: string | number) {
     key = hyphenizeCss(key)
     value = autoVar(value)
     if (this.props.get(key) === value) return this
     this.props.set(key, value)
-    RootStyle.revision += 1
+    this.changed()
     return this
   }
 
@@ -92,7 +107,7 @@ export class BaseStyle<T extends RootStyle> extends RootStyle {
     this.#asBaseStyle(css).props.forEach((value, key) => {
       if (this.props.get(key) === value) return
       this.props.set(key, value)
-      RootStyle.revision += 1
+      this.changed()
     })
     return this
   }

packages/ts-page-scripts/README.md

@@ -29,14 +29,16 @@ Three separate plugins from this package are also enabled by default:
 | --- | --- | --- |
 | `authStateHintPlugin()` | `purestack:auth-state-hint` | Apply the signed-in hint before stylesheets load, when auth is enabled |
 | `consentPlugin()` | `purestack:consent` | Initialize the consent browser runtime when consent is enabled |
-| `analyticsPlugin()` | `purestack:analytics` | Add direct GA4 scripts without consent, or register the consent-managed GA4 service during `onConfigResolved` |
+| `analyticsPlugin()` | `purestack:analytics` | Add direct GA4 scripts without consent, or contribute the consent-managed GA4 service during configuration resolution |
 
 Each factory can be selected independently of `pageScriptsPlugin()`. Omitting
 analytics removes automatic GA4 service registration as well as direct scripts;
 explicit user-defined consent services are preserved. When consent is enabled,
 analytics never bypasses it, including when the consent runtime plugin is omitted.
 The raw `resolveSiteConfig` result contains only explicitly configured consent
-services; automatic GA4 registration occurs when the analytics plugin initializes,
-before later config hooks and page rendering.
+services; automatic GA4 registration runs in `config.finalize`, after all
+configuration overrides and before
+styles, components, highlighters, search providers, and config hooks initialize.
+Omitting the analytics plugin also omits this contribution.
 
 For standalone `renderApp` calls, use `appendRuntimeScripts(document, runtimeEmbeds, frontmatter.embed)` from the renderer's `onRendered(document, runtimeEmbeds)` callback. The renderer itself has no knowledge of individual runtimes.

packages/ts-page-scripts/src/analyticsPlugin.ts

@@ -3,7 +3,7 @@ import type {
   ConsentService,
   Ga4Config,
   PageTemplateInput,
-  SiteConfig,
+  SiteConfigResolution,
 } from '@purestack/ts-common'
 import { h } from '@purestack/ts-html'
 import { buildGa4Script } from './buildGa4Script'
@@ -12,14 +12,19 @@ import { buildGa4Script } from './buildGa4Script'
 export function analyticsPlugin() {
   return {
     name: 'purestack:analytics',
-    hooks: {
-      onConfigResolved({ config }: { config: SiteConfig }) {
-        if (config.consent.enabled)
-          config.consent.services = appendGa4ConsentService(
-            config.consent.services,
-            config.consent.categories,
-            config.analytics.ga4,
-          )
+    config: {
+      finalize({ config }: SiteConfigResolution) {
+        return {
+          consent: {
+            services: config.consent.enabled
+              ? appendGa4ConsentService(
+                  config.consent.services,
+                  config.consent.categories,
+                  config.analytics.ga4,
+                )
+              : config.consent.services,
+          },
+        }
       },
     },
     head({ head, site }: PageTemplateInput) {

packages/ts-seo/src/preview.test.ts

@@ -2,6 +2,24 @@ import { describe, expect, it } from 'vitest'
 import { resolvePreviewConfig } from './preview'
 
 describe('social preview defaults', () => {
+  it.each([
+    ['  https://example.com///  ', 'https://example.com/guide/'],
+    [`https://example.com/${'/'.repeat(20_000)}`, 'https://example.com/guide/'],
+    [
+      `https://example.com/${'/'.repeat(20_000)}tail`,
+      'https://example.com/guide/',
+    ],
+    ['/'.repeat(20_000), undefined],
+    ['   ', undefined],
+  ])(
+    'normalizes base URLs with whitespace and repeated slashes (%#)',
+    (baseUrl, expected) => {
+      expect(
+        resolvePreviewConfig({}, { baseUrl, urlPath: '/guide/' }).canonicalUrl,
+      ).toBe(expected)
+    },
+  )
+
   it('preserves title fallbacks, absolute URLs, image dimensions, and Twitter defaults', () => {
     const head = resolvePreviewConfig(
       { title: 'Getting Started', description: 'Build your first thing.' },

packages/ts-seo/src/preview.ts

@@ -156,8 +156,10 @@ function resolveAbsoluteUrl(
 
 function normalizeBaseUrl(value: string | undefined): string | undefined {
   if (typeof value !== 'string') return undefined
-  const trimmed = value.trim().replace(/\/+$/, '')
-  return trimmed.length > 0 ? trimmed : undefined
+  const trimmed = value.trim()
+  let end = trimmed.length
+  while (end > 0 && trimmed[end - 1] === '/') end--
+  return end > 0 ? trimmed.slice(0, end) : undefined
 }
 
 function pickString(...values: Array<string | undefined>): string | undefined {

packages/ts-ssg/README.md

@@ -334,7 +334,7 @@ Plugins can supply a `head` template, with the same input as a page template and
 
 Metadata defaults compose through `headConfig({ site, pageInfo })` in plugin order, before explicit frontmatter `head` overrides and before head markup is rendered. It returns `BasicHeadConfig` or a promise. The SEO plugin uses this contribution for Open Graph, Twitter, canonical URLs, and translated alternate links; page templates receive the completed `headConfig`. Basic titles, descriptions, explicit head settings, and `index: false` enforcement remain in core.
 
-Auth hints, consent, and analytics are independent plugins in `ts-page-scripts`. The analytics plugin registers automatic GA4 consent services during `onConfigResolved`, before later config hooks and rendering. Omitting it removes automatic registration and direct tracking scripts. Explicitly configured consent services remain available. Analytics never bypasses enabled consent when the consent runtime plugin is omitted.
+Auth hints, consent, and analytics are independent plugins in `ts-page-scripts`. The analytics plugin contributes automatic GA4 consent services during configuration resolution, before any factory or lifecycle hook runs. Omitting it removes automatic registration and direct tracking scripts. Explicitly configured consent services remain available. Analytics never bypasses enabled consent when the consent runtime plugin is omitted.
 
 The theme plugin supplies `styles(config)`, which returns the `SiteStyles` writer used for full builds and lazy development assets. Only one plugin can supply it. Component, template, and default highlighter contributions marked `defaults: true` may be overridden by ordinary contributions; this flag controls merge precedence and never schedules hooks or factories. Conflicts within either group remain errors.
 
@@ -407,6 +407,51 @@ Plugins apply in order:
 
 Each plugin is checked when the build starts. An unknown field or hook name, such as `onPageRender`, a value of the wrong type, two plugins sharing a name, or two plugins defining the same skin, component, template, or generated page fails the build with the plugin's name. For a single hook, pass an inline plugin: `{ name: 'site', hooks: { … } }`.
 
+### Plugin configuration
+
+Plugins contribute configuration through `config.resolve({ config, input, file })` and `config.finalize({ config, input, file })`. Both are optional and synchronous. Each returns an object to merge into the config; do not mutate the inputs. All resolvers run first in plugin order, applying configuration overrides. Then all finalizers run in plugin order, deriving dependent settings from the completed overrides. Finalizers should derive settings rather than change resolver inputs. Both phases finish before highlighters, Markdown processors, styles, search providers, components, and templates initialize. The analytics plugin finalizes its automatic GA4 service here, so later site resolvers can enable analytics, change its ID or category, or provide a manual service. The existing `onConfigResolved` hook still runs after factories, so it can customize initialized components and templates. Publishing applies its output-directory and minification overrides after configuration composition.
+
+Custom site settings belong under `extensions` in `siteConfig.json`. File values merge with programmatic input, which takes precedence. The standard JSON schema allows plugin namespaces here while continuing to reject unknown top-level fields. Each plugin owns validation, defaults, and normalization for its namespace. Other namespaces are preserved.
+
+```json
+{ "extensions": { "brand": { "label": "Acme" } } }
+```
+
+Use TypeScript module augmentation for typed settings:
+
+```ts
+import { definePlugin } from 'purestack'
+
+declare module '@purestack/ts-common' {
+  interface SiteExtensions {
+    brand?: { label: string }
+  }
+}
+
+export const brandPlugin = definePlugin({
+  name: 'brand',
+  config: {
+    resolve({ config }) {
+      const brand = config.extensions.brand
+      if (brand !== undefined &&
+          (brand === null || typeof brand !== 'object' ||
+           typeof brand.label !== 'string')) {
+        throw new Error('extensions.brand requires a string label.')
+      }
+      return { extensions: { brand: { label: brand?.label ?? 'Docs' } } }
+    },
+  },
+  components(config) {
+    // config.extensions.brand contains the normalized settings here.
+    return {}
+  },
+})
+```
+
+Raw `resolveSiteConfig(input)` resolves core settings and extension input. CLI and programmatic builds additionally compose their selected plugins' configuration contributions. Configuration contributions are synchronous and may run whenever a project configuration is resolved; keep file writes and other side effects in lifecycle hooks.
+
+Builder style state is isolated across asynchronous operations, including concurrent sites. Its owned theme options remain linked to `context.config.style.theme`, so in-place config-hook changes and `themes.setOptions` update page colors, CSS, and generated favicons consistently. Head, metadata, template, Markdown, provider, and lifecycle errors identify their owning plugin and preserve the original cause. Markdown wrappers preserve unified presets, duplicate-plugin option merging, and callback transforms.
+
 ### Code highlighting
 
 Use `markdown.resolveHighlighter(lang)` to select a code-to-HTML callback for a language: