Hardcoded components, theme, and page-scripts packages are now plugins.

Author: koculu

.github/pull_request_template.md

@@ -1,11 +1,11 @@
-## Change
+## Summary
 
-Describe the problem and resulting behavior. Link a related issue if applicable.
+Summarize the change.
 
-## Validation
+## Changes
+
+Describe the changes.
 
-Describe the checks you ran and include screenshots for visible UI changes.
+## Validation
 
-- [ ] Relevant tests and documentation updated.
-- [ ] CI passes.
-- [ ] Required generated assets regenerated manually, if applicable.
+Describe the validation.

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

@@ -89,6 +89,33 @@ yarn purestack serve --content ./content
 
 The badge appears on the page. Change its `tone` in `plugins/site.ts` while the server runs: the site rebuilds and the page reloads. `build` and `publish` load the same config, so the published site gets the same badge.
 
+## Standard plugins
+
+PureStack includes three plugins automatically in `build`, `serve`, and `publish`:
+
+| Package | Factory | Provides |
+| --- | --- | --- |
+| `@purestack/ts-components` | `componentsPlugin()` | Standard components, icons, and component styles |
+| `@purestack/ts-theme` | `themePlugin()` | The `doc` and `splash` templates, generated theme CSS, and theme switching |
+| `@purestack/ts-page-scripts` | `pageScriptsPlugin()` | Auth hint, consent and analytics, menus, navigation, code copying, search, and TOC runtimes |
+
+The stylesheet provider initializes before component factories, then all config hooks run in plugin order. Names do not affect initialization. Components belong to each build, so hooks can override them through `context.components`. The theme and page runtime plugins supply head templates that run before the selected page template, preserving its ability to inspect or change the completed head. The lifecycle hook set is unchanged.
+
+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:
+
+```ts
+import { componentsPlugin, defineConfig, themePlugin } from 'purestack'
+
+export default defineConfig({
+  defaultPlugins: false,
+  plugins: [themePlugin(), componentsPlugin()],
+})
+```
+
+This keeps the layouts and components while omitting the page runtimes. Theme switching belongs to the theme plugin; component-specific Tabs and Modal embeds still follow the page's `embed` settings. Without the theme plugin, another plugin must supply your page templates and any CSS output you need.
+
+An explicitly listed standard plugin replaces the automatic instance by name and keeps its initialization position. You can also use `createDefaultPlugins()` to obtain the complete set. In programmatic builds, use `options.defaultPlugins` alongside `options.plugins`.
+
 ## 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: [...] })`.
@@ -496,9 +523,12 @@ Every field except `name` is optional.
 | Field | Type |
 | --- | --- |
 | `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 }` |
 | `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 |
+| `styles` | `(config) => SiteStyles`; one stylesheet provider, initialized before component factories |
 | `markdown` | `{ remarkPlugins?: PluggableList, rehypePlugins?: PluggableList }` |
 | `pages` | `({ config, files }) => { path, source }[]`, or a promise of them; `source` is the text, or a function that returns it |
 | `hooks` | Any of the hooks above |

frontend/purestack.studio/siteConfig.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../packages/ts-ssg/schema/siteConfig.schema.json",
+  "$schema": "https://raw.githubusercontent.com/PureStackStudio/PureStack/refs/heads/main/packages/ts-ssg/schema/siteConfig.schema.json",
   "siteTitle": "PureStack",
   "favicon": "tabler:stack-2",
   "style": {

packages/ts-common/src/index.ts

@@ -11,6 +11,7 @@ export type {
   PageFrontmatter,
   ParsedFrontmatterSource,
 } from './frontmatter-types'
+export { isTocEnabled } from './isTocEnabled'
 export type {
   ClassicLogoConfig,
   LogoAppearance,
@@ -32,6 +33,7 @@ export type {
   PageNavigationLinks,
 } from './navMenu-types'
 export type {
+  PageHeadTemplate,
   PageInfo,
   PageTemplate,
   PageTemplateInput,
@@ -62,6 +64,7 @@ export type {
   SiteStyleConfig,
   SiteStyleConfigInput,
 } from './site-config-types'
+export type { SiteStyles, WriteStylesResult } from './site-styles'
 export type {
   PageContext,
   PageOutlineItem,

packages/ts-ssg/src/toc/isTocEnabled.ts packages/ts-common/src/isTocEnabled.tspackages/ts-ssg/src/toc/isTocEnabled.ts renamed to packages/ts-common/src/isTocEnabled.ts

@@ -1,4 +1,5 @@
-import type { PageFrontmatter, PageOutlineItem } from '@purestack/ts-common'
+import type { PageFrontmatter } from './frontmatter-types'
+import type { PageOutlineItem } from './ts-ssg-context'
 
 export function isTocEnabled(
   frontmatter: PageFrontmatter,

packages/ts-common/src/page-template-types.ts

@@ -39,3 +39,8 @@ export type PageTemplate = (
 ) => TSNode<'html'> | Promise<TSNode<'html'>>
 
 export type PageTemplateMap = Record<string, PageTemplate>
+
+/** Composes head markup before the page template receives it. */
+export type PageHeadTemplate = (
+  input: PageTemplateInput,
+) => TSNode<'head'> | Promise<TSNode<'head'>>

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

@@ -0,0 +1,18 @@
+import type { ThemeStylesheetLink } from '@purestack/ts-style'
+
+export interface WriteStylesResult {
+  revision: number
+  outPath: string
+  outputs: string[]
+  signature: string
+}
+
+/** A plugin's stylesheet output, initialized before component factories. */
+export interface SiteStyles {
+  readonly revision: number
+  links(cacheKey?: string): ThemeStylesheetLink[]
+  write(input: {
+    outDir: string
+    cacheKey?: string
+  }): Promise<WriteStylesResult>
+}

packages/ts-components/README.md

@@ -8,3 +8,16 @@ by the static site generator and available to custom renderers.
 `registerStyles()` adds its styles to PureStack's theme builder. Individual
 component definitions and style registration functions are also exported when
 you need a smaller selection.
+
+`componentsPlugin()` integrates these components, SVG icons, and their styles
+as default contributions scoped to each build. It is enabled by default by
+`@purestack/ts-ssg` and can also be imported from this package:
+
+```ts
+import { componentsPlugin } from '@purestack/ts-components'
+```
+
+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`.

packages/ts-components/package.json

@@ -54,6 +54,7 @@
     "@purestack/ts-css": "workspace:^",
     "@purestack/ts-page-scripts": "workspace:^",
     "@purestack/ts-style": "workspace:^",
+    "@purestack/ts-svg-icons": "workspace:^",
     "@purestack/ts-util": "workspace:^",
     "regor": "^1.7.5"
   },

packages/ts-components/src/index.ts

@@ -15,6 +15,7 @@ export type {
   TsSsgTabsApi,
 } from '@purestack/ts-page-scripts'
 export { defineComponents } from './defineComponents'
+export { componentsPlugin } from './plugin'
 export { registerStyles } from './registerStyles'
 export type { AlertBox } from './standard/alertBox/alertBox'
 export { defineAlertComponents } from './standard/alertBox/alertBox'