Move integration-specific configuration into its owning plugins and add optional image optimization through @purestack/ts-images. Preserve existing default site output while making plugin configuration and asset lifecycle contracts explicit.

Author: koculu

frontend/components/studioBrand.ts

@@ -6,7 +6,7 @@ import {
 import { defineComponent, html, type RefOrValue } from 'regor'
 
 export interface StudioBrand {
-  config: LogoConfig
+  config?: LogoConfig
   size?: RefOrValue<LogoSize>
 }
 

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

@@ -132,10 +132,14 @@ The Pagefind plugin supplies a `search` provider. To use another engine, replace
 
 ## 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.
+`resolveSiteConfig(input)` returns `DefaultSiteConfig` for the untouched standard set. Calls supplying a `plugins` array return `SiteConfig`, even when automatic defaults remain enabled, because a supplied plugin can replace a standard owner by name.
+
+Plugins contribute configuration through optional, synchronous `config.resolve`, `config.normalize`, and `config.finalize` functions, each receiving `{ config, input, file }` and returning an object to merge into config. Do not mutate the inputs. All resolvers run first in plugin order to supply defaults and overrides. All normalizers then validate and canonicalize the completed overrides. Finally, all finalizers derive dependent settings from the normalized config. Finalizers should not change the inputs used by other finalizers. Every phase finishes before highlighters, Markdown processors, styles, search providers, components, and templates initialize. Analytics derives its automatic GA4 consent service only after every normalizer finishes, regardless of plugin order. The existing `onConfigResolved` hook still runs after factories. 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.
 
+`resolve` and `normalize` receive `SiteConfigDraft`: core fields are ready, while plugin settings can still be partial, including nested extension values. `finalize` receives normalized `SiteConfig` after all selected owners finish normalization. Factories run afterwards. Importing a plugin's setting types does not install its owner; select that plugin before depending on its normalized settings.
+
 ```json
 { "extensions": { "brand": { "label": "Acme" } } }
 ```
@@ -171,10 +175,29 @@ export const brandPlugin = definePlugin({
 })
 ```
 
-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.
+`resolveSiteConfig(input, { plugins, defaultPlugins })` composes the same selected plugins as a build, including the standard plugins by default. Plugin-owned sections (`style`, `docLayout`, `pageToc`, `logo`, `auth`, `consent`, `analytics`, `pagefind`, and `preview`) are optional in `SiteConfig`: an omitted plugin does not supply defaults or validate its unused input. A replacement plugin reads its settings from `input` and `file`, then contributes normalized config. Analytics also resolves explicitly configured consent when its browser runtime is omitted, so enabled consent is never bypassed. 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.
 
+## Optimize images
+
+Image optimization is optional. Install `@purestack/ts-images` alongside PureStack and add it to your existing plugin list:
+
+```ts
+import { defineConfig } from 'purestack'
+import { imagesPlugin } from '@purestack/ts-images'
+
+export default defineConfig({
+  plugins: [imagesPlugin({ widths: [480, 960, 1440] })],
+})
+```
+
+Ordinary Markdown images and rendered HTML images receive responsive AVIF/WebP sources, JPEG/PNG fallbacks, dimensions, and loading defaults. Originals remain available for links and downloads. Remote images, SVGs, animations, existing `picture` markup, and images with `srcset` pass through. Use `data-image-preset="hero"` for eager priority images, `data-image-preset="screenshot"` for lossless output, or `data-image-optimize="false"` to keep an individual image unchanged. Set `sizes` for your actual image layout.
+
+The plugin owns its `extensions.images` settings, persistent cache, and encoder limits. It uses the generic asset contribution: `assets(config)` returns a per-site processor with a unique namespace and `processPage(input)`. This runs after all `onPageDocument` hooks, before URL rewriting. `resolveSource(element, url)` resolves local inputs and registers dependencies; `dependOn(relPath)` registers additional inputs; `emit(fileName, bytes)` atomically writes an owned file and returns its URL. Use content-addressed names and await all writes. Core handles base paths, incremental invalidation, shared references, manifest persistence, and cleanup when pages or processors disappear. The builder contains no image format or encoder selection.
+
+Asset processors run in order within each page, and different page requests can run them concurrently. Keep page-local state inside `processPage`; coordinate shared caches and queues within the processor instance. Await source resolution and emission before returning. Input methods then close, and detached work cannot emit files after page completion. Later processors see earlier DOM edits, while `resolveSource` continues to resolve original content files only. Combine transforms inside one processor when they need intermediate generated bytes. Ownership receipts and processor instances remain private to the builder.
+
 ## 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: [...] })`.
@@ -586,7 +609,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 |
+| `config` | `{ resolve?: SiteConfigResolver, normalize?: SiteConfigResolver, finalize?: SiteConfigFinalizer }`; overrides, normalization, 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

@@ -52,9 +52,15 @@ export {
   resolvePageContext,
   tryResolvePageContext,
 } from './resolvePageContext'
+export type {
+  AssetSource,
+  PageAssetInput,
+  SiteAssets,
+} from './site-assets'
 export type {
   AnalyticsConfig,
   AuthConfig,
+  CoreSiteConfig,
   DocLayoutConfig,
   Ga4Config,
   I18nConfig,
@@ -65,6 +71,8 @@ export type {
   RobotsConfig,
   SiteConfig,
   SiteConfigContributions,
+  SiteConfigDraft,
+  SiteConfigFinalizer,
   SiteConfigInput,
   SiteConfigResolution,
   SiteConfigResolver,

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

@@ -0,0 +1,29 @@
+/** A local source selected through the site's URL and locale resolution rules. */
+export interface AssetSource {
+  relPath: string
+  absPath: string
+  /** Root-relative URL, without the site's base path. */
+  publicPath: string
+}
+
+export interface PageAssetInput {
+  document: Document
+  sourceRelPath: string
+  /** Resolves original content assets and records dependencies. Generated outputs are not resolver inputs. */
+  resolveSource: (
+    element: Element,
+    url: string,
+  ) => Promise<AssetSource | undefined>
+  /** Records another content-root-relative input, including a file not yet created. */
+  dependOn: (relPath: string) => void
+  /** Await writes before returning. Use immutable content-addressed names within this namespace. */
+  emit: (fileName: string, data: Uint8Array) => Promise<string>
+}
+
+/** Each build/session owns its processors; core handles generated files and invalidation. */
+export interface SiteAssets {
+  /** A unique path segment under /_assets/. */
+  namespace: string
+  /** Ordered within a page; different pages may run concurrently. Input methods expire when this call completes. */
+  processPage: (input: PageAssetInput) => void | Promise<void>
+}

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

@@ -8,33 +8,37 @@ import type { ConsentConfig } from './consent-types'
 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
+/** Settings normalized by the builder before plugin configuration runs. */
+export interface CoreSiteConfig {
   rootDir: string
   contentDir: string
   outDir: string
   publishDir: string
   basePath: string
   siteTitle: string
-  favicon?: string
-  logo: SiteLogoConfig
-  docLayout: DocLayoutConfig
-  style: SiteStyleConfig
   html: SiteHtmlConfig
   navigation: NavigationConfig
-  pageToc: PageTocConfig
-  auth: AuthConfig
   scripts: SiteScriptsConfig
   sitemap: SitemapConfig
-  consent: ConsentConfig
-  analytics: AnalyticsConfig
-  pagefind: PagefindConfig
-  preview: PreviewConfig
   i18n: I18nConfig
   mdx: SiteMdxConfig
 }
 
+export interface SiteConfig extends CoreSiteConfig {
+  /** Plugin-owned settings, normalized by the installed owners. */
+  extensions: SiteExtensions
+  favicon?: string
+  logo?: SiteLogoConfig
+  docLayout?: DocLayoutConfig
+  style?: SiteStyleConfig
+  pageToc?: PageTocConfig
+  auth?: AuthConfig
+  consent?: ConsentConfig
+  analytics?: AnalyticsConfig
+  pagefind?: PagefindConfig
+  preview?: PreviewConfig
+}
+
 /** Plugins may augment this interface with optional, typed namespaces. */
 export interface SiteExtensions {
   [plugin: string]: unknown
@@ -140,7 +144,8 @@ export interface I18nConfig {
 }
 
 export interface SiteMdxConfig {
-  highlighter: 'shiki' | 'highlightjs'
+  /** An optional provider-owned backend identifier. Core does not select an engine. */
+  highlighter?: string
   disableHighlighter: boolean
   compileMdAsMdx: boolean
 }
@@ -155,9 +160,15 @@ export type SiteConfigInput = DeepPartial<Omit<SiteConfig, 'style'>> & {
   style?: SiteStyleConfigInput
 }
 
+/** Core fields are ready; plugin sections may still contain partial input. */
+export type SiteConfigDraft = CoreSiteConfig &
+  Omit<SiteConfigInput, keyof CoreSiteConfig | 'extensions'> & {
+    extensions: DeepPartial<SiteExtensions>
+  }
+
 /** Inputs for a pure configuration contribution, before build factories run. */
-export interface SiteConfigResolution {
-  config: SiteConfig
+export interface SiteConfigResolution<TConfig = SiteConfigDraft> {
+  config: TConfig
   input: SiteConfigInput
   file: SiteConfigInput
 }
@@ -166,8 +177,14 @@ export type SiteConfigResolver = (
   source: SiteConfigResolution,
 ) => DeepPartial<SiteConfig>
 
-/** All overrides resolve before any plugin derives dependent settings. */
+/** Runs after every installed owner's normalizer has completed. */
+export type SiteConfigFinalizer = (
+  source: SiteConfigResolution<SiteConfig>,
+) => DeepPartial<SiteConfig>
+
+/** Overrides, normalization, then dependent settings; all run before factories. */
 export interface SiteConfigContributions {
   resolve?: SiteConfigResolver
-  finalize?: SiteConfigResolver
+  normalize?: SiteConfigResolver
+  finalize?: SiteConfigFinalizer
 }

packages/ts-common/src/ts-ssg-context.ts

@@ -29,7 +29,7 @@ export interface PageContext {
   pageInfo: PageInfo
   navigation?: TsSsgNavigation
   outline?: PageOutlineItem[]
-  theme: ThemeOptions
+  theme?: ThemeOptions
   basePath: string
   locale?: string
   locales: string[]

packages/ts-components/README.md

@@ -21,3 +21,5 @@ Extension component factories and config hooks can override standard components
 through `context.components` and register styles. When choosing plugins explicitly with `defaultPlugins: false`,
 include `@purestack/ts-theme` to emit CSS, or supply your own style writer through
 `context.styles`.
+
+The components plugin owns the site `logo` defaults and normalization. Without it, a custom plugin may contribute `logo`; components also accept an absent site logo config.

packages/ts-components/src/logoConfig.ts

@@ -0,0 +1,135 @@
+import type { SiteLogoConfig } from '@purestack/ts-common'
+import { pickSemanticTone } from '@purestack/ts-style'
+import type { DeepPartial } from '@purestack/ts-util'
+import {
+  resolveConfigUrl,
+  resolveOptionalString,
+  resolveString,
+} from '@purestack/ts-util'
+
+export function resolveSiteLogoConfig(
+  input?: DeepPartial<SiteLogoConfig>,
+  file?: DeepPartial<SiteLogoConfig>,
+): SiteLogoConfig {
+  const href = input?.href !== undefined ? input.href : file?.href
+  return {
+    brand: resolveString(input?.brand, file?.brand, 'Pure Stack'),
+    letterColors: resolveOptionalString(
+      input?.letterColors ?? file?.letterColors,
+    ),
+    subtitleLetterColors: resolveOptionalString(
+      input?.subtitleLetterColors ?? file?.subtitleLetterColors,
+    ),
+    brandSizeSm: resolveOptionalString(input?.brandSizeSm ?? file?.brandSizeSm),
+    brandSizeMd: resolveOptionalString(input?.brandSizeMd ?? file?.brandSizeMd),
+    brandSizeLg: resolveOptionalString(input?.brandSizeLg ?? file?.brandSizeLg),
+    brandSizeXl: resolveOptionalString(input?.brandSizeXl ?? file?.brandSizeXl),
+    subtitleSizeSm: resolveOptionalString(
+      input?.subtitleSizeSm ?? file?.subtitleSizeSm,
+    ),
+    subtitleSizeMd: resolveOptionalString(
+      input?.subtitleSizeMd ?? file?.subtitleSizeMd,
+    ),
+    subtitleSizeLg: resolveOptionalString(
+      input?.subtitleSizeLg ?? file?.subtitleSizeLg,
+    ),
+    subtitleSizeXl: resolveOptionalString(
+      input?.subtitleSizeXl ?? file?.subtitleSizeXl,
+    ),
+    iconSize: resolveOptionalString(input?.iconSize ?? file?.iconSize),
+    iconSizeSm: resolveOptionalString(input?.iconSizeSm ?? file?.iconSizeSm),
+    iconSizeMd: resolveOptionalString(input?.iconSizeMd ?? file?.iconSizeMd),
+    iconSizeLg: resolveOptionalString(input?.iconSizeLg ?? file?.iconSizeLg),
+    iconSizeXl: resolveOptionalString(input?.iconSizeXl ?? file?.iconSizeXl),
+    subtitleInset: resolveOptionalString(
+      input?.subtitleInset ?? file?.subtitleInset,
+    ),
+    subtitleInsetSm: resolveOptionalString(
+      input?.subtitleInsetSm ?? file?.subtitleInsetSm,
+    ),
+    subtitleInsetMd: resolveOptionalString(
+      input?.subtitleInsetMd ?? file?.subtitleInsetMd,
+    ),
+    subtitleInsetLg: resolveOptionalString(
+      input?.subtitleInsetLg ?? file?.subtitleInsetLg,
+    ),
+    subtitleInsetXl: resolveOptionalString(
+      input?.subtitleInsetXl ?? file?.subtitleInsetXl,
+    ),
+    component: resolveOptionalString(input?.component ?? file?.component),
+    colors: (input?.colors ?? file?.colors)?.filter(
+      (color): color is string => typeof color === 'string',
+    ),
+    logoBackground: input?.logoBackground ?? file?.logoBackground,
+    logoForeground: input?.logoForeground ?? file?.logoForeground,
+    href:
+      href === null || href === ''
+        ? href
+        : resolveConfigUrl(resolveString(href, '/')),
+    subtitle: resolveOptionalString(input?.subtitle ?? file?.subtitle),
+    suffix: resolveOptionalString(input?.suffix ?? file?.suffix),
+    ariaLabel: resolveOptionalString(input?.ariaLabel ?? file?.ariaLabel),
+    icon: resolveOptionalString(input?.icon ?? file?.icon),
+    imageSrc: resolveConfigUrl(
+      resolveOptionalString(input?.imageSrc ?? file?.imageSrc),
+    ),
+    imageSrcDark: resolveConfigUrl(
+      resolveOptionalString(input?.imageSrcDark ?? file?.imageSrcDark),
+    ),
+    monogram: resolveOptionalString(input?.monogram ?? file?.monogram),
+    brandColor: resolveOptionalString(input?.brandColor ?? file?.brandColor),
+    accentColor: resolveOptionalString(input?.accentColor ?? file?.accentColor),
+    markBackground: resolveOptionalString(
+      input?.markBackground ?? file?.markBackground,
+    ),
+    markColor: resolveOptionalString(input?.markColor ?? file?.markColor),
+    brandSize: resolveOptionalString(input?.brandSize ?? file?.brandSize),
+    subtitleSize: resolveOptionalString(
+      input?.subtitleSize ?? file?.subtitleSize,
+    ),
+    markSize: resolveOptionalString(input?.markSize ?? file?.markSize),
+    gap: resolveOptionalString(input?.gap ?? file?.gap),
+    layout: resolveLogoChoice(input?.layout ?? file?.layout, [
+      'horizontal',
+      'stacked',
+      'wordmark',
+      'mark',
+    ] as const),
+    size: resolveLogoChoice(input?.size ?? file?.size, [
+      'sm',
+      'md',
+      'lg',
+      'xl',
+    ] as const),
+    appearance: resolveLogoChoice(input?.appearance ?? file?.appearance, [
+      'plain',
+      'badge',
+      'outline',
+    ] as const),
+    markStyle: resolveLogoChoice(input?.markStyle ?? file?.markStyle, [
+      'plain',
+      'soft',
+      'solid',
+      'outline',
+    ] as const),
+    wordmarkStyle: resolveLogoChoice(
+      input?.wordmarkStyle ?? file?.wordmarkStyle,
+      ['plain', 'accent', 'gradient'] as const,
+    ),
+    shape: resolveLogoChoice(input?.shape ?? file?.shape, [
+      'rounded',
+      'square',
+      'circle',
+    ] as const),
+    tone: pickSemanticTone(input?.tone, file?.tone),
+  }
+}
+
+function resolveLogoChoice<T extends string>(
+  value: unknown,
+  choices: readonly T[],
+): T | undefined {
+  return typeof value === 'string' && choices.includes(value as T)
+    ? (value as T)
+    : undefined
+}

packages/ts-components/src/plugin.ts

@@ -1,13 +1,29 @@
+import type { SiteConfigResolution } from '@purestack/ts-common'
 import { registerSemanticToneUtilityStyles } from '@purestack/ts-style'
 import { getSvgIcon } from '@purestack/ts-svg-icons'
+import { merge } from '@purestack/ts-util'
 import { defineComponents } from './defineComponents'
+import { resolveSiteLogoConfig } from './logoConfig'
 import { registerStyles } from './registerStyles'
 
 /** The standard server-rendered components and their shared CSS. */
 export function componentsPlugin() {
   return {
     name: 'purestack:components',
     defaults: true,
+    config: {
+      resolve({ config, input, file }: SiteConfigResolution) {
+        return {
+          logo: merge(
+            resolveSiteLogoConfig(input.logo, file.logo),
+            config.logo,
+          ),
+        }
+      },
+      normalize({ config }: SiteConfigResolution) {
+        return { logo: resolveSiteLogoConfig(config.logo) }
+      },
+    },
     components(): Record<string, object> {
       registerStyles()
       registerSemanticToneUtilityStyles()