@jaamd/jaad 0.0.0-stage → 1.0.0-rc.1

package/src/site/config.ts

@@ -0,0 +1,149 @@
+import type { Locale } from './locales.ts'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { z } from 'astro/zod'
+import { inferDescription, type RepoInfo } from './infer.ts'
+import { PRESETS, PRESET_NAMES, isPreset } from './themes.ts'
+
+const publicUrl = (field: string, example: string) =>
+    z.string().refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+        message: `${field} must be a public url, such as "${example}"`,
+    })
+
+/** The options of the site around the pages: identity, header, footer, head and theme. */
+export const siteConfigShape = {
+    title: z.string(),
+    description: z.string().optional(),
+    lang: z.string().default('en'),
+    logo: publicUrl('logo', '/logo.svg').optional(),
+    /** Where the site name in the header leads: the site root, or another site. */
+    homeLink: z.string().default('/'),
+
+    social: z
+        .record(
+            z.string(),
+            z.union([
+                z.string(),
+                z.object({
+                    href: z.string(),
+                    label: z.string().optional(),
+                    svg: z.string().optional(),
+                }),
+            ]),
+        )
+        .default({}),
+    nav: z.array(z.object({ label: z.string(), href: z.string() })).default([]),
+    footer: z
+        .union([z.string(), z.literal(false)], {
+            error:
+                'footer is one line of text, or false to remove it. ' +
+                'The message/copyright pair is gone: write them as a single string, ' +
+                'e.g. "MIT Licensed · © 2026 Me · :credit".',
+        })
+        .optional(),
+
+    head: z
+        .array(
+            z.object({
+                tag: z.string(),
+                attrs: z.record(z.string(), z.union([z.string(), z.boolean()])).optional(),
+                content: z.string().optional(),
+            }),
+        )
+        .default([]),
+    ogImage: z.union([publicUrl('ogImage', '/og-image.png'), z.literal(false)]).optional(),
+
+    theme: z
+        .union([
+            z.string().refine(isPreset, {
+                message: `unknown theme; available: ${PRESET_NAMES.join(', ')}`,
+            }),
+            z.object({ light: z.string(), dark: z.string() }),
+        ])
+        .default('default'),
+
+    appearance: z
+        .enum(['auto', 'light', 'dark'], {
+            error: 'unknown appearance; available: auto, light, dark',
+        })
+        .default('auto'),
+
+    /** Registers Tailwind (the site's own install) and exposes JAAD's tokens to it. */
+    tailwind: z.boolean().default(false),
+
+    /** Per-locale overrides for JAAD's bundled interface strings. */
+    ui: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+}
+
+const siteConfigSchema = z.object(siteConfigShape)
+
+export type SiteConfig = z.output<typeof siteConfigSchema>
+
+/** The site options plus what the project could tell. Inferred fields are null
+ *  when unavailable. */
+export interface SiteResolvedConfig extends SiteConfig {
+    /** What jaamd gets for code blocks. */
+    shiki: string | { light: string; dark: string }
+    repoUrl: string | null
+    favicon: string | null
+    /** Explicit, inferred from public/, or false when no valid image exists. */
+    ogImage: string | false
+    /** Empty when the site is not localised. */
+    locales: Locale[]
+    /** `lang` when the site is not localised. */
+    defaultLocale: string
+}
+
+const FAVICONS = ['favicon.svg', 'favicon.ico', 'favicon.png']
+const OG_IMAGES = ['og-image.png', 'og-image.jpg', 'og-image.jpeg', 'og-image.webp']
+
+function findPublicAsset(cwd: string, candidates: string[]): string | null {
+    for (const name of candidates) {
+        if (existsSync(join(cwd, 'public', name))) return `/${name}`
+    }
+    return null
+}
+
+/** The fields the site derives from its options and the project. */
+export function resolveSiteConfig(
+    config: SiteConfig,
+    repo: RepoInfo | null,
+    cwd: string,
+): Pick<SiteResolvedConfig, 'description' | 'repoUrl' | 'favicon' | 'ogImage' | 'shiki'> {
+    return {
+        description: config.description ?? inferDescription(cwd) ?? undefined,
+        repoUrl: repo?.url ?? null,
+        favicon: findPublicAsset(cwd, FAVICONS),
+        ogImage: config.ogImage ?? findPublicAsset(cwd, OG_IMAGES) ?? false,
+        shiki: typeof config.theme === 'string' ? PRESETS[config.theme].shiki : config.theme,
+    }
+}
+
+const requireFrom = createRequire(import.meta.url)
+
+const styleInPackage = (name: string) => fileURLToPath(new URL(`./styles/${name}`, import.meta.url))
+
+/** Absolute paths, kept off the resolved config, which gets serialised. */
+export function resolveStylesheets(
+    config: SiteConfig,
+    cwd: string = process.cwd(),
+): {
+    user: string | null
+    theme: string | null
+    bridge: string
+    tailwind: string | null
+} {
+    const userCss = join(cwd, 'src', 'jaad.css')
+    const slug = typeof config.theme === 'string' ? PRESETS[config.theme].theme : null
+
+    return {
+        user: existsSync(userCss) ? userCss : null,
+        // Resolved through JAAMD's export map rather than by path.
+        theme: slug ? requireFrom.resolve(`@jaamd/astro/themes/${slug}.css`) : null,
+        // A preset supplies the palette, so the colours travel the other way.
+        bridge: styleInPackage(slug ? 'jaamd-reverse.css' : 'jaamd-forward.css'),
+        tailwind: config.tailwind ? styleInPackage('tailwind.css') : null,
+    }
+}

package/src/site/fonts/OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter)
+Copyright 2020 The Merriweather Project Authors (https://github.com/EbenSorkin/Merriweather4) with Reserved Font Name "Merriweather".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/site/fonts.ts

@@ -0,0 +1,29 @@
+import { fontProviders } from 'astro/config'
+
+const file = (name: string) => new URL(`./fonts/${name}.woff2`, import.meta.url)
+
+export const fonts = [
+    {
+        provider: fontProviders.local(),
+        name: 'Inter',
+        cssVariable: '--font-inter',
+        options: {
+            variants: [{ weight: '400 600', style: 'normal', src: [file('inter')] }],
+        },
+    },
+    {
+        provider: fontProviders.local(),
+        name: 'Merriweather',
+        cssVariable: '--font-merriweather',
+        options: {
+            variants: [
+                { weight: '300 700', style: 'normal', src: [file('merriweather')] },
+                {
+                    weight: '300 700',
+                    style: 'italic',
+                    src: [file('merriweather-italic')],
+                },
+            ],
+        },
+    },
+]

package/src/site/forges.ts

@@ -0,0 +1,60 @@
+// Icon paths from simple-icons (CC0-1.0). Only git forges are bundled: they
+// are what the repository link inferred from the git remote needs.
+
+interface Forge {
+    label: string
+    /** Single 24×24 filled path. */
+    path: string
+    /** Host that identifies this forge in a git remote, when unambiguous. */
+    host: string | null
+}
+
+export const FORGES: Record<string, Forge> = {
+    github: {
+        label: 'GitHub',
+        host: 'github.com',
+        path: 'M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12',
+    },
+    gitlab: {
+        label: 'GitLab',
+        host: 'gitlab.com',
+        path: 'm23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z',
+    },
+    codeberg: {
+        label: 'Codeberg',
+        host: 'codeberg.org',
+        path: 'M11.999.747A11.974 11.974 0 0 0 0 12.75c0 2.254.635 4.465 1.833 6.376L11.837 6.19c.072-.092.251-.092.323 0l4.178 5.402h-2.992l.065.239h3.113l.882 1.138h-3.674l.103.374h3.86l.777 1.003h-4.358l.135.483h4.593l.695.894h-5.038l.165.589h5.326l.609.785h-5.717l.182.65h6.038l.562.727h-6.397l.183.65h6.717A12.003 12.003 0 0 0 24 12.75 11.977 11.977 0 0 0 11.999.747zm3.654 19.104.182.65h5.326c.173-.204.353-.433.513-.65zm.385 1.377.18.65h3.563c.233-.198.485-.428.712-.65zm.383 1.377.182.648h1.203c.356-.204.685-.412 1.042-.648z',
+    },
+    gitea: {
+        label: 'Gitea',
+        host: 'gitea.com',
+        path: 'M4.209 4.603c-.247 0-.525.02-.84.088-.333.07-1.28.283-2.054 1.027C-.403 7.25.035 9.685.089 10.052c.065.446.263 1.687 1.21 2.768 1.749 2.141 5.513 2.092 5.513 2.092s.462 1.103 1.168 2.119c.955 1.263 1.936 2.248 2.89 2.367 2.406 0 7.212-.004 7.212-.004s.458.004 1.08-.394c.535-.324 1.013-.893 1.013-.893s.492-.527 1.18-1.73c.21-.37.385-.729.538-1.068 0 0 2.107-4.471 2.107-8.823-.042-1.318-.367-1.55-.443-1.627-.156-.156-.366-.153-.366-.153s-4.475.252-6.792.306c-.508.011-1.012.023-1.512.027v4.474l-.634-.301c0-1.39-.004-4.17-.004-4.17-1.107.016-3.405-.084-3.405-.084s-5.399-.27-5.987-.324c-.187-.011-.401-.032-.648-.032zm.354 1.832h.111s.271 2.269.6 3.597C5.549 11.147 6.22 13 6.22 13s-.996-.119-1.641-.348c-.99-.324-1.409-.714-1.409-.714s-.73-.511-1.096-1.52C1.444 8.73 2.021 7.7 2.021 7.7s.32-.859 1.47-1.145c.395-.106.863-.12 1.072-.12zm8.33 2.554c.26.003.509.127.509.127l.868.422-.529 1.075a.686.686 0 0 0-.614.359.685.685 0 0 0 .072.756l-.939 1.924a.69.69 0 0 0-.66.527.687.687 0 0 0 .347.763.686.686 0 0 0 .867-.206.688.688 0 0 0-.069-.882l.916-1.874a.667.667 0 0 0 .237-.02.657.657 0 0 0 .271-.137 8.826 8.826 0 0 1 1.016.512.761.761 0 0 1 .286.282c.073.21-.073.569-.073.569-.087.29-.702 1.55-.702 1.55a.692.692 0 0 0-.676.477.681.681 0 1 0 1.157-.252c.073-.141.141-.282.214-.431.19-.397.515-1.16.515-1.16.035-.066.218-.394.103-.814-.095-.435-.48-.638-.48-.638-.467-.301-1.116-.58-1.116-.58s0-.156-.042-.27a.688.688 0 0 0-.148-.241l.516-1.062 2.89 1.401s.48.218.583.619c.073.282-.019.534-.069.657-.24.587-2.1 4.317-2.1 4.317s-.232.554-.748.588a1.065 1.065 0 0 1-.393-.045l-.202-.08-4.31-2.1s-.417-.218-.49-.596c-.083-.31.104-.691.104-.691l2.073-4.272s.183-.37.466-.497a.855.855 0 0 1 .35-.077z',
+    },
+    forgejo: {
+        label: 'Forgejo',
+        host: null,
+        path: 'M16.7773 0c1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.1175a7.0759 7.0759 0 0 1 4.148-1.4205l.1176-.001 1.3385.0002c.4973-.8827 1.4434-1.4788 2.5288-1.4788 1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.319c.8827.4973 1.4788 1.4434 1.4788 2.5287 0 1.602-1.2986 2.9005-2.9005 2.9005-1.6018 0-2.9004-1.2986-2.9004-2.9005 0-1.0853.596-2.0314 1.4788-2.5287l-.0002-9.9831c0-3.887 3.1195-7.0453 6.9915-7.108l.1176-.001h1.3385C14.7458.5962 15.692 0 16.7773 0ZM7.2227 19.9052c-.6596 0-1.1943.5347-1.1943 1.1943s.5347 1.1943 1.1943 1.1943 1.1944-.5347 1.1944-1.1943-.5348-1.1943-1.1944-1.1943Zm9.5546-10.4644c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Zm0-7.7346c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Z',
+    },
+    bitbucket: {
+        label: 'Bitbucket',
+        host: 'bitbucket.org',
+        path: 'M.778 1.213a.768.768 0 00-.768.892l3.263 19.81c.084.5.515.868 1.022.873H19.95a.772.772 0 00.77-.646l3.27-20.03a.768.768 0 00-.768-.891zM14.52 15.53H9.522L8.17 8.466h7.561z',
+    },
+    sourcehut: {
+        label: 'SourceHut',
+        host: 'sr.ht',
+        path: 'M12 0C5.371 0 0 5.371 0 12s5.371 12 12 12 12-5.371 12-12S18.629 0 12 0Zm0 21.677A9.675 9.675 0 0 1 2.323 12 9.675 9.675 0 0 1 12 2.323 9.675 9.675 0 0 1 21.677 12 9.675 9.675 0 0 1 12 21.677Z',
+    },
+}
+
+/** Matches a repository URL to a bundled forge icon, if we recognise the host. */
+export function forgeForUrl(url: string): string | null {
+    const host = url.match(/^https?:\/\/([^/]+)/)?.[1]
+    if (!host) return null
+    for (const [name, forge] of Object.entries(FORGES)) {
+        if (forge.host && (host === forge.host || host.endsWith('.' + forge.host))) {
+            return name
+        }
+    }
+    return null
+}

package/src/site/helpers.ts

@@ -0,0 +1,4 @@
+export function ucfirst(str: string): string {
+    if (str.length === 0) return str
+    return str.charAt(0).toUpperCase() + str.slice(1)
+}

package/src/site/infer.ts

@@ -0,0 +1,75 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { join, posix } from 'node:path'
+
+const git = (args: string[], cwd: string): string | null => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim()
+    } catch {
+        return null
+    }
+}
+
+/** `git@host:owner/repo.git` and `https://host/owner/repo.git` both become
+ *  `https://host/owner/repo`. */
+export function normaliseRemote(remote: string): string | null {
+    const ssh = remote.match(/^[\w.-]+@([\w.-]+):(.+?)(?:\.git)?$/)
+    if (ssh) return `https://${ssh[1]}/${ssh[2]}`
+
+    const https = remote.match(/^https?:\/\/(?:[^@/]+@)?([\w.-]+)\/(.+?)(?:\.git)?$/)
+    if (https) return `https://${https[1]}/${https[2]}`
+
+    return null
+}
+
+export interface RepoInfo {
+    /** Browsable base, e.g. https://github.com/owner/repo */
+    url: string
+    branch: string
+    /** Path from the repository root to the Astro project, "" at the root. */
+    prefix: string
+}
+
+/** Returns null outside a repository, in a tarball, or without an origin. */
+export function inferRepo(cwd: string = process.cwd()): RepoInfo | null {
+    const remote = git(['remote', 'get-url', 'origin'], cwd)
+    if (!remote) return null
+
+    const url = normaliseRemote(remote)
+    if (!url) return null
+
+    return {
+        url,
+        branch: git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) || 'main',
+        prefix: git(['rev-parse', '--show-prefix'], cwd) ?? '',
+    }
+}
+
+/** Ends in a slash. `docsDir` resolves against the repository root, not the
+ *  Astro project, so a site in a subdirectory still links correctly. */
+export function editBaseFrom(repo: RepoInfo, docsDir: string): string {
+    // Normalised: a section can sit outside the project, as `../packages/x/docs`.
+    const path = posix.normalize(`${repo.prefix}${docsDir}`).replace(/^\/+|\/+$/g, '')
+    return `${repo.url}/edit/${repo.branch}/${path}/`
+}
+
+/** `:path` is substituted when present, otherwise the file is appended. */
+export function editUrl(base: string, filePath: string): string {
+    return base.includes(':path') ? base.replace(':path', filePath) : base.replace(/\/?$/, '/') + filePath
+}
+
+export function inferDescription(cwd: string = process.cwd()): string | null {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as {
+            description?: unknown
+        }
+
+        return typeof pkg.description === 'string' && pkg.description ? pkg.description : null
+    } catch {
+        return null
+    }
+}

package/src/site/integration.ts

@@ -0,0 +1,59 @@
+import type { SiteResolvedConfig } from './config.ts'
+import type { SiteStylesheets } from './virtual.ts'
+import type { AstroIntegration, AstroUserConfig } from 'astro'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fonts } from './fonts.ts'
+import { siteVirtualPlugin } from './virtual.ts'
+
+type SetupParams = Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0]
+type VitePlugins = NonNullable<NonNullable<AstroUserConfig['vite']>['plugins']>
+
+const NOT_INSTALLED = new Set(['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'])
+
+/** The site's own `@tailwindcss/vite`, unless it already registered one. */
+export function loadTailwindPlugin(root: string, registered: VitePlugins | undefined): VitePlugins {
+    const plugins = ([registered] as unknown[]).flat(Infinity) as ({
+        name?: string
+    } | null)[]
+    if (plugins.some((p) => p?.name?.startsWith('@tailwindcss/vite'))) return []
+
+    const load = createRequire(join(root, 'package.json'))
+    let tailwindcss: () => VitePlugins
+    try {
+        load.resolve('tailwindcss/package.json')
+        ;({ default: tailwindcss } = load('@tailwindcss/vite') as {
+            default: () => VitePlugins
+        })
+    } catch (error) {
+        if (!NOT_INSTALLED.has((error as { code?: string }).code ?? '')) throw error
+        throw new Error(
+            'jaad: `tailwind: true` needs Tailwind in your project:\n  npm i -D tailwindcss @tailwindcss/vite',
+            { cause: error },
+        )
+    }
+    return tailwindcss()
+}
+
+/** The virtual modules, Tailwind when asked for, and the fonts. `config` is
+ *  what `virtual:jaad/config` serves. */
+export function setupSite(
+    { config: astroConfig, updateConfig }: SetupParams,
+    config: SiteResolvedConfig,
+    stylesheets: SiteStylesheets,
+): void {
+    updateConfig({
+        vite: {
+            plugins: [
+                siteVirtualPlugin(config, stylesheets),
+                ...(config.tailwind
+                    ? [loadTailwindPlugin(fileURLToPath(astroConfig.root), astroConfig.vite.plugins)]
+                    : []),
+            ],
+            // Package .astro sources must reach the Astro compiler.
+            ssr: { noExternal: ['@jaamd/jaad'] },
+        },
+        fonts,
+    })
+}

package/src/site/layouts/Shell.astro

@@ -0,0 +1,41 @@
+---
+import type { ComponentProps } from 'astro/types'
+import config from 'virtual:jaad/config'
+import Footer from '../components/Footer.astro'
+import Head from '../components/Head.astro'
+import Header from '../components/Header.astro'
+import '../../../dist/jaad.css'
+import 'virtual:jaad/theme.css'
+import 'virtual:jaad/bridge.css'
+import 'virtual:jaad/user.css'
+import 'virtual:jaad/tailwind.css'
+
+interface Props {
+    title?: string
+    description?: string
+    bare?: boolean
+    /** Added to the body. */
+    class?: string
+    /** What the header offers: translations and search. */
+    header: ComponentProps<typeof Header>
+}
+
+const { title, description, bare = false, class: className, header } = Astro.props
+
+const pageTitle = title ? `${title} | ${config.title}` : config.title
+const pageDescription = description ?? config.description ?? config.title
+---
+
+<!doctype html>
+<html lang={config.lang} class={config.appearance === 'dark' ? 'dark' : undefined}>
+    <head>
+        <Head title={pageTitle} description={pageDescription} />
+    </head>
+    <body class:list={['jaad-body', className]}>
+        <Header {...header} />
+        <main class={bare ? 'jaad-main-bare' : 'jaad-main'}>
+            <slot />
+        </main>
+        <Footer />
+    </body>
+</html>