@texuli/astro 0.0.0-stage → 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @texuli/astro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Astro 7 integration, token stylesheet, static content components, and a closed
+content-block parser for Texuli sites. The package is private and source-first
+while Texuli is in development; it is not published to npm.
+
+## Install and configure
+
+Add the Astro Svelte integration when the site uses Svelte islands, then add
+Texuli's integration to the Astro config:
+
+```ts
+import svelte from '@astrojs/svelte';
+import { defineConfig } from 'astro/config';
+import { texuli } from '@texuli/astro';
+
+export default defineConfig({
+  integrations: [svelte(), texuli({ namespace: 'docs' })],
+});
+```
+
+Import the Texuli stylesheet once from a site-owned global stylesheet:
+
+```css
+@import '@texuli/astro/styles.css';
+```
+
+Use the same `namespace` in Texuli's appearance writer and the integration so
+the early bootstrap reads the cache entry that the site writes. The default
+namespace is `site`. See [integration setup and CSP](docs/integration.md) and
+[stylesheet contents](docs/styles.md).
+
+## Entry points
+
+| Import | Purpose | Documentation |
+| --- | --- | --- |
+| `@texuli/astro` | `texuli`, `themeBootstrapScript`, `TexuliAstroOptions`, density/radius types, and `parseTexuliBlocks` | [Integration](docs/integration.md), [content parser](docs/content.md) |
+| `@texuli/astro/integration` | Integration and theme-bootstrap API | [Integration](docs/integration.md) |
+| `@texuli/astro/content` | Closed-schema content-block parser | [Content parser](docs/content.md) |
+| `@texuli/astro/site` | Validated site model, page metadata and sitemap for Protoyard static sites | [Site model](docs/site.md) |
+| `@texuli/astro/styles.css` | Token base, forced-colors rules, density/radius variants, and print rules | [Stylesheet](docs/styles.md) |
+| `@texuli/astro/layouts/ContentLayout` | Semantic HTML document shell | [ContentLayout](docs/layouts-content-layout.md) |
+| `@texuli/astro/sections/Hero` | Static hero section | [Hero](docs/sections-hero.md) |
+| `@texuli/astro/sections/Section` | Static width-constrained section | [Section](docs/sections-section.md) |
+
+The package peers on Astro Svelte integration and Svelte 5 for sites that use
+Svelte islands. The layout and section components in this package render static
+HTML and do not hydrate themselves.
+
+## Components and content
+
+```astro
+---
+import '@texuli/astro/styles.css';
+import ContentLayout from '@texuli/astro/layouts/ContentLayout';
+import Hero from '@texuli/astro/sections/Hero';
+import Section from '@texuli/astro/sections/Section';
+---
+
+<ContentLayout title="Stories" description="A collection of stories.">
+  <Hero title="Stories" align="center">
+    <a href="https://example.com/stories">Browse stories</a>
+  </Hero>
+  <Section width="reading">
+    <p>Static Astro content.</p>
+  </Section>
+</ContentLayout>
+```
+
+For structured content, `parseTexuliBlocks(value)` validates unknown input
+against `@texuli/blocks` and returns either the typed blocks or schema issues.
+It does not render HTML or interpret unknown block types. See [content
+parsing](docs/content.md). For whole-site definitions — pages, navigation,
+canonical metadata and a sitemap — `defineSite` validates the export and
+returns the frozen model the layouts consume. See the [site
+model](docs/site.md). The Protoyard `site` export that fills this model is
+planned on the Protoyard side.
+
+## Fixtures and checks
+
+The packed consumer fixtures live under `tests/consumers/fixtures/`:
+
+- `astro-plain` installs the packed Astro package, uses this integration and
+  stylesheet, renders the layout and sections, and includes a Svelte smoke
+  island.
+- `astro-tailwind` checks the Astro/Tailwind consumer path with token CSS; it
+  does not install `@texuli/astro`.
+
+Package behavior is covered by `packages/astro/tests/content.test.ts`,
+`packages/astro/tests/integration.test.ts`, and
+`packages/astro/tests/site.test.ts`. The consumer harness builds and
+serves the packed fixtures in `tests/consumers/consumers.spec.ts`.
+
+```bash
+pnpm vitest run packages/astro
+pnpm --filter @texuli/astro typecheck
+npx biome check packages/astro
+pnpm verify:packages --filter packages/astro
+```
+
+The package source and exports are listed in [`package.json`](package.json).

package/dist/content/index.d.ts

@@ -0,0 +1,11 @@
+/// <reference path="../css-modules.d.ts" />
+import { type Block, type FieldIssue } from '@texuli/blocks/core';
+export type ParsedTexuliBlocks = {
+    success: true;
+    blocks: Block[];
+} | {
+    success: false;
+    issues: FieldIssue[];
+};
+/** Parse a content entry's block field using the closed Texuli block schema. */
+export declare function parseTexuliBlocks(value: unknown): ParsedTexuliBlocks;

package/dist/content/index.js

@@ -0,0 +1,8 @@
+import { safeParseBlocks } from '@texuli/blocks/core';
+/** Parse a content entry's block field using the closed Texuli block schema. */
+export function parseTexuliBlocks(value) {
+    const parsed = safeParseBlocks(value);
+    if (!parsed.success)
+        return { success: false, issues: parsed.issues };
+    return { success: true, blocks: parsed.data };
+}

package/dist/css-modules.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./css-modules.d.ts" />
+export { type ParsedTexuliBlocks, parseTexuliBlocks } from './content/index.js';
+export { type TexuliAstroOptions, type TexuliDensityVariant, type TexuliRadiusVariant, texuli, themeBootstrapScript, } from './integration/index.js';
+export { defineSite, SITE_KIND, sitePage, sitePageMeta, siteSitemap, type TexuliSite, type TexuliSiteInput, type TexuliSiteNavEntry, type TexuliSitePage, type TexuliSitePageInput, } from './site/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { parseTexuliBlocks } from "./content/index.js";
+export { texuli, themeBootstrapScript, } from "./integration/index.js";
+export { defineSite, SITE_KIND, sitePage, sitePageMeta, siteSitemap, } from "./site/index.js";

package/dist/integration/index.d.ts

@@ -0,0 +1,25 @@
+/// <reference path="../css-modules.d.ts" />
+import type { ColorMode } from '@texuli/tokens/modes';
+import type { AstroIntegration } from 'astro';
+export type TexuliDensityVariant = 'compact' | 'comfortable' | 'spacious';
+export type TexuliRadiusVariant = 'compact' | 'comfortable' | 'rounded';
+export interface TexuliAstroOptions {
+    /** Namespace shared with the appearance switcher that writes the token cache. */
+    namespace?: string;
+    /** Mode used without a cached appearance. Defaults to the active system preference. */
+    fallbackMode?: ColorMode;
+    /** Select a token density variant on the document root before styles paint. */
+    density?: TexuliDensityVariant;
+    /** Select a token radius scale on the document root before styles paint. */
+    radius?: TexuliRadiusVariant;
+    /** Use Astro's inline-script injection, or render the exported body with a host nonce. */
+    bootstrap?: 'injected' | 'manual';
+}
+/**
+ * Return the deterministic inline theme bootstrap body. It restores the cached
+ * appearance before paint, follows system preference changes when uncached,
+ * and applies same-origin storage updates without a reload or network request.
+ */
+export declare function themeBootstrapScript(options?: TexuliAstroOptions): string;
+/** Install the deterministic, CSP-compatible early theme bootstrap for Astro. */
+export declare function texuli(options?: TexuliAstroOptions): AstroIntegration;

package/dist/integration/index.js

@@ -0,0 +1,72 @@
+import { COLOR_MODE_NAMES } from '@texuli/tokens/modes';
+import { appearanceCacheKey, noFlashScript } from '@texuli/tokens/no-flash';
+const DENSITIES = ['compact', 'comfortable', 'spacious'];
+const RADII = ['compact', 'comfortable', 'rounded'];
+function optionJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+function validateOptions(options) {
+    const namespace = options.namespace ?? 'site';
+    const fallbackMode = options.fallbackMode ?? 'system';
+    const bootstrap = options.bootstrap ?? 'injected';
+    // Keep validation aligned with the token cache's namespaced contract.
+    appearanceCacheKey(namespace);
+    noFlashScript(namespace, fallbackMode);
+    if (!COLOR_MODE_NAMES.includes(fallbackMode)) {
+        throw new TypeError('Fallback mode must be a supported Texuli color mode.');
+    }
+    if (options.density !== undefined && !DENSITIES.includes(options.density)) {
+        throw new TypeError('Density must be compact, comfortable, or spacious.');
+    }
+    if (options.radius !== undefined && !RADII.includes(options.radius)) {
+        throw new TypeError('Radius must be compact, comfortable, or rounded.');
+    }
+    if (bootstrap !== 'injected' && bootstrap !== 'manual') {
+        throw new TypeError('Bootstrap must be injected or manual.');
+    }
+    return { namespace, fallbackMode, bootstrap, density: options.density, radius: options.radius };
+}
+/**
+ * Return the deterministic inline theme bootstrap body. It restores the cached
+ * appearance before paint, follows system preference changes when uncached,
+ * and applies same-origin storage updates without a reload or network request.
+ */
+export function themeBootstrapScript(options = {}) {
+    const { namespace, fallbackMode, density, radius } = validateOptions(options);
+    const key = optionJson(appearanceCacheKey(namespace));
+    const densityJson = density ? optionJson(density) : 'null';
+    const radiusJson = radius ? optionJson(radius) : 'null';
+    const initial = noFlashScript(namespace, fallbackMode);
+    const sync = `(function(){var d=document.documentElement,k=${key},f=${optionJson(fallbackMode)},dv=${densityJson},rv=${radiusJson},applied=[];` +
+        `function validValue(v){return typeof v==='string'&&v.length<=2048&&!/[;{}<>]/.test(v)&&!/[\\x00-\\x1f\\x7f]/.test(v)&&!/(?:url\\s*\\(|expression\\s*\\(|var\\s*\\(|javascript:|@import)/i.test(v);}` +
+        `function read(raw){try{var c=JSON.parse(raw||'null');if(!c||c.v!==1||typeof c.themeId!=='string'||!/^[a-z][a-z0-9-]{0,79}$/.test(c.themeId)||(c.mode!=='light'&&c.mode!=='dark'&&c.mode!=='high-contrast')||!c.vars||typeof c.vars!=='object'||Array.isArray(c.vars))return null;var vars={};for(var n in c.vars){if(Object.prototype.hasOwnProperty.call(c.vars,n)&&/^--tx-[a-z0-9-]+$/.test(n)&&validValue(c.vars[n]))vars[n]=c.vars[n];}return {themeId:c.themeId,mode:c.mode,vars:vars,reducedMotion:c.reducedMotion,surface:c.surface,components:c.components||{}};}catch(e){return null;}}` +
+        `function modeFromSystem(){try{if(matchMedia('(prefers-contrast: more)').matches)return 'high-contrast';return matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';}catch(e){return 'light';}}` +
+        `function setMode(m){d.dataset.txMode=m;d.classList.toggle('dark',m==='dark');d.classList.toggle('light',m==='light');d.style.colorScheme=m==='high-contrast'?'light dark':m;}` +
+        `function setVariant(){if(dv)d.dataset.txDensity=dv;else delete d.dataset.txDensity;if(rv)d.dataset.txRadius=rv;else delete d.dataset.txRadius;}` +
+        `function apply(c){for(var i=0;i<applied.length;i++)d.style.removeProperty(applied[i]);applied=[];if(!c){delete d.dataset.txTheme;delete d.dataset.txMotion;delete d.dataset.txSurface;delete d.dataset.txButtonStyle;delete d.dataset.txCardStyle;delete d.dataset.txFocusRingStyle;setMode(f==='system'?modeFromSystem():f);return;}d.dataset.txTheme=c.themeId;for(var n in c.vars){var v=c.vars[n];if(dv&&n==='--tx-density')v=String(${density === 'compact' ? '0.875' : density === 'spacious' ? '1.125' : '1'});if(rv&&n==='--tx-radius-scale')v=String(${radius === 'compact' ? '0.75' : radius === 'rounded' ? '1.25' : '1'});if(rv&&(n==='--tx-radius'||/^--tx-radius-step-[0-9]+$/.test(n)))v='calc('+v+' * '+(${radius === 'compact' ? '0.75' : radius === 'rounded' ? '1.25' : '1'})+')';d.style.setProperty(n,v);applied.push(n);}if(dv&&!c.vars['--tx-density']){d.style.setProperty('--tx-density',${density === 'compact' ? "'0.875'" : density === 'spacious' ? "'1.125'" : "'1'"});applied.push('--tx-density');}if(rv&&!c.vars['--tx-radius-scale']){d.style.setProperty('--tx-radius-scale',${radius === 'compact' ? "'0.75'" : radius === 'rounded' ? "'1.25'" : "'1'"});applied.push('--tx-radius-scale');}if(c.reducedMotion===true||c.reducedMotion===false)d.dataset.txMotion=c.reducedMotion?'reduce':'full';else delete d.dataset.txMotion;if(c.surface==='glass'||c.surface==='solid')d.dataset.txSurface=c.surface;else delete d.dataset.txSurface;var p=c.components;if(p.button==='pill'||p.button==='square')d.dataset.txButtonStyle=p.button;else delete d.dataset.txButtonStyle;if(p.card==='glass'||p.card==='bordered')d.dataset.txCardStyle=p.card;else delete d.dataset.txCardStyle;if(p.focusRing==='ring'||p.focusRing==='outline'||p.focusRing==='glow'||p.focusRing==='inset')d.dataset.txFocusRingStyle=p.focusRing;else delete d.dataset.txFocusRingStyle;setMode(c.mode);}` +
+        `function current(){try{return read(localStorage.getItem(k));}catch(e){return null;}}` +
+        `function syncSystem(){if(f==='system'&&!current())setMode(modeFromSystem());}` +
+        `var boot=current();if(boot)for(var name in boot.vars)if(/^--tx-[a-z0-9-]+$/.test(name)&&validValue(boot.vars[name]))applied.push(name);setVariant();apply(boot);if(typeof addEventListener==='function')addEventListener('storage',function(e){if(e.key===k)apply(read(e.newValue));});` +
+        `if(f==='system'&&typeof matchMedia==='function'){var q1=matchMedia('(prefers-color-scheme: dark)'),q2=matchMedia('(prefers-contrast: more)');if(q1.addEventListener)q1.addEventListener('change',syncSystem);else if(q1.addListener)q1.addListener(syncSystem);if(q2.addEventListener)q2.addEventListener('change',syncSystem);else if(q2.addListener)q2.addListener(syncSystem);}` +
+        `})();`;
+    return `${initial}${sync}`;
+}
+/** Install the deterministic, CSP-compatible early theme bootstrap for Astro. */
+export function texuli(options = {}) {
+    const normalized = validateOptions(options);
+    const script = themeBootstrapScript(normalized);
+    return {
+        name: '@texuli/astro',
+        hooks: {
+            'astro:config:setup': ({ injectScript }) => {
+                if (normalized.bootstrap === 'injected')
+                    injectScript('head-inline', script);
+            },
+        },
+    };
+}

package/dist/layouts/ContentLayout.astro

@@ -0,0 +1,68 @@
+---
+import { safeHref } from '@texuli/core/url-policy';
+import type { TexuliDensityVariant, TexuliRadiusVariant } from '../integration/index.ts';
+
+interface Props {
+  title: string;
+  description?: string;
+  lang?: string;
+  theme?: string;
+  canonical?: string;
+  /** Static token density variant; matches the integration's script-driven attribute. */
+  density?: TexuliDensityVariant;
+  /** Static token radius scale; matches the integration's script-driven attribute. */
+  radius?: TexuliRadiusVariant;
+  ogTitle?: string;
+  ogDescription?: string;
+  /** Open Graph image; rendered only when it passes the developer URL policy. */
+  ogImage?: string;
+  /** Asks crawlers to skip the page; use for drafts and staging mirrors. */
+  noindex?: boolean;
+}
+
+const DENSITIES: readonly TexuliDensityVariant[] = ['compact', 'comfortable', 'spacious'];
+const RADII: readonly TexuliRadiusVariant[] = ['compact', 'comfortable', 'rounded'];
+
+const {
+  title,
+  description,
+  lang = 'en',
+  theme = 'default',
+  canonical,
+  density,
+  radius,
+  ogTitle,
+  ogDescription,
+  ogImage,
+  noindex = false,
+} = Astro.props;
+
+if (density !== undefined && !DENSITIES.includes(density)) {
+  throw new TypeError('Density must be compact, comfortable, or spacious.');
+}
+if (radius !== undefined && !RADII.includes(radius)) {
+  throw new TypeError('Radius must be compact, comfortable, or rounded.');
+}
+
+const canonicalHref = safeHref(canonical, 'developer');
+const ogImageHref = safeHref(ogImage, 'developer');
+---
+
+<!doctype html>
+<html lang={lang} data-tx-theme={theme} data-tx-density={density} data-tx-radius={radius}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    {canonicalHref && <link rel="canonical" href={canonicalHref} />}
+    {ogTitle && <meta property="og:title" content={ogTitle} />}
+    {ogDescription && <meta property="og:description" content={ogDescription} />}
+    {ogImageHref && <meta property="og:image" content={ogImageHref} />}
+    {noindex && <meta name="robots" content="noindex" />}
+    <slot name="head" />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>

package/dist/layouts/ContentLayout.d.ts

@@ -0,0 +1,3 @@
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+declare const _default: AstroComponentFactory;
+export default _default;

package/dist/layouts/ContentLayout.js

@@ -0,0 +1,4 @@
+// Astro's compiler resolves this source component when consuming the packed wrapper.
+// @ts-expect-error Astro files are handled by Astro rather than TypeScript's resolver.
+import ContentLayoutSource from './ContentLayout.astro';
+export default ContentLayoutSource;

package/dist/sections/Hero.astro

@@ -0,0 +1,34 @@
+---
+interface Props {
+  eyebrow?: string;
+  title: string;
+  description?: string;
+  align?: 'start' | 'center';
+  /** `lede` (default) for page tops; `compact` for sub-pages and nested views. */
+  size?: 'lede' | 'compact';
+}
+
+const { eyebrow, title, description, align = 'start', size = 'lede' } = Astro.props;
+---
+
+<header
+  class:list={['tx-astro-hero', `tx-astro-hero--${align}`, `tx-astro-hero--${size}`]}
+>
+  {eyebrow && <p class="tx-astro-hero__eyebrow">{eyebrow}</p>}
+  <h1>{title}</h1>
+  {description && <p class="tx-astro-hero__description">{description}</p>}
+  <div class="tx-astro-hero__actions"><slot /></div>
+</header>
+
+<style>
+  .tx-astro-hero { display: grid; gap: 1rem; padding-block: clamp(3rem, 9vw, 7rem); }
+  .tx-astro-hero--center { text-align: center; justify-items: center; }
+  .tx-astro-hero__eyebrow { color: var(--tx-color-accent-foreground, inherit); font-weight: 600; margin: 0; }
+  h1 { font-size: clamp(2.5rem, 7vw, 5rem); line-height: 1.05; max-inline-size: 16ch; margin: 0; }
+  .tx-astro-hero__description { color: var(--tx-color-muted-foreground, currentColor); font-size: 1.125rem; line-height: 1.6; max-inline-size: 62ch; margin: 0; }
+  .tx-astro-hero__actions { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-block-start: 0.5rem; }
+
+  .tx-astro-hero--compact { gap: 0.75rem; padding-block: clamp(1.5rem, 5vw, 3rem); }
+  .tx-astro-hero--compact h1 { font-size: clamp(1.75rem, 4.5vw, 2.75rem); }
+  .tx-astro-hero--compact .tx-astro-hero__description { font-size: 1rem; }
+</style>

package/dist/sections/Hero.d.ts

@@ -0,0 +1,3 @@
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+declare const _default: AstroComponentFactory;
+export default _default;

package/dist/sections/Hero.js

@@ -0,0 +1,4 @@
+// Astro's compiler resolves this source component when consuming the packed wrapper.
+// @ts-expect-error Astro files are handled by Astro rather than TypeScript's resolver.
+import HeroSource from './Hero.astro';
+export default HeroSource;

package/dist/sections/Section.astro

@@ -0,0 +1,42 @@
+---
+interface Props {
+  id?: string;
+  label?: string;
+  width?: 'reading' | 'wide' | 'full';
+  /** `surface` paints the theme's surface color behind the section. */
+  tone?: 'default' | 'surface';
+  /** `none` removes the responsive inline padding, for nesting sections. */
+  padding?: 'normal' | 'none';
+}
+
+const { id, label, width = 'reading', tone = 'default', padding = 'normal' } = Astro.props;
+---
+
+<section
+  id={id}
+  aria-label={label}
+  class:list={[
+    'tx-astro-section',
+    `tx-astro-section--${width}`,
+    `tx-astro-section--${tone}`,
+    `tx-astro-section--padding-${padding}`,
+  ]}
+>
+  <slot />
+</section>
+
+<style>
+  .tx-astro-section {
+    box-sizing: border-box;
+    margin-inline: auto;
+    padding-inline: clamp(1rem, 4vw, 2rem);
+    inline-size: 100%;
+  }
+
+  .tx-astro-section--reading { max-inline-size: 72rem; }
+  .tx-astro-section--wide { max-inline-size: 88rem; }
+  .tx-astro-section--full { max-inline-size: none; }
+
+  .tx-astro-section--surface { background: var(--tx-surface); }
+  .tx-astro-section--padding-none { padding-inline: 0; }
+</style>

package/dist/sections/Section.d.ts

@@ -0,0 +1,3 @@
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+declare const _default: AstroComponentFactory;
+export default _default;

package/dist/sections/Section.js

@@ -0,0 +1,4 @@
+// Astro's compiler resolves this source component when consuming the packed wrapper.
+// @ts-expect-error Astro files are handled by Astro rather than TypeScript's resolver.
+import SectionSource from './Section.astro';
+export default SectionSource;

package/dist/site/index.d.ts

@@ -0,0 +1,86 @@
+/// <reference path="../css-modules.d.ts" />
+import { type Block } from '@texuli/blocks/core';
+/**
+ * The site kind identifier that Protoyard static-site exports declare. A
+ * `defineSite` input may carry it to fail fast when a future revision of the
+ * contract changes shape; today only this revision exists.
+ */
+export declare const SITE_KIND = "texuli.site/v1";
+export interface TexuliSitePageInput {
+    /** kebab-case path segment; the home page's slug is ignored in favor of `home`. */
+    slug: string;
+    title: string;
+    description?: string;
+    /** ISO calendar date (YYYY-MM-DD) emitted as the sitemap `lastmod` when set. */
+    updated?: string;
+    /** Navigation label; a page with one joins `site.navigation` in declared order. */
+    nav?: string;
+    /** Marks the site's home page; exactly one page per site sets it. */
+    home?: boolean;
+    /** Page content validated against the closed Texuli block schema. */
+    blocks?: unknown;
+}
+export interface TexuliSiteInput {
+    /** Contract discriminator; when present it must be `texuli.site/v1`. */
+    kind?: string;
+    name: string;
+    /** Deployed origin plus optional base path, without a trailing slash. */
+    url: string;
+    /** BCP 47-ish document language; defaults to `en`. */
+    lang?: string;
+    pages: TexuliSitePageInput[];
+}
+export interface TexuliSitePage {
+    slug: string;
+    /** Root path for the home page, otherwise `/${slug}`. */
+    path: string;
+    title: string;
+    description?: string;
+    updated?: string;
+    nav?: string;
+    home: boolean;
+    /** Absolute same-origin URL built from the site base. */
+    href: string;
+    blocks: Block[];
+}
+export interface TexuliSiteNavEntry {
+    slug: string;
+    label: string;
+    href: string;
+}
+export interface TexuliSite {
+    name: string;
+    url: string;
+    lang: string;
+    pages: TexuliSitePage[];
+    navigation: TexuliSiteNavEntry[];
+}
+/**
+ * Validate a static-site definition and return the frozen, normalized model
+ * that Protoyard `site` exports hand to the layouts, navigation and sitemap
+ * helpers. Throws a `TypeError` naming the offending field when any part of
+ * the closed schema fails: one home page, unique lowercase kebab-case slugs,
+ * an http(s) base URL without query or fragment, and page content that
+ * passes the closed Texuli block schema. Blocks are validated but never
+ * rendered here; painting them stays with the host's sink-free renderer.
+ */
+export declare function defineSite(input: TexuliSiteInput): TexuliSite;
+/** Return the site's page for a slug, or `undefined` when absent. */
+export declare function sitePage(site: TexuliSite, slug: string): TexuliSitePage | undefined;
+/**
+ * Metadata for a page as ContentLayout props: the home page titles as the
+ * site name, others as `page title — site name`; the canonical is the
+ * page's absolute URL.
+ */
+export declare function sitePageMeta(site: TexuliSite, slug: string): {
+    title: string;
+    description?: string;
+    canonical: string;
+    lang: string;
+} | undefined;
+/**
+ * Deterministic sitemap XML for the site: one entry per page in declared
+ * order, with `lastmod` only for pages that declare an `updated` date. The
+ * result is data for a `sitemap.xml` endpoint, never HTML.
+ */
+export declare function siteSitemap(site: TexuliSite): string;

package/dist/site/index.js

@@ -0,0 +1,182 @@
+import { safeParseBlocks } from '@texuli/blocks/core';
+import { safeHref } from '@texuli/core/url-policy';
+/**
+ * The site kind identifier that Protoyard static-site exports declare. A
+ * `defineSite` input may carry it to fail fast when a future revision of the
+ * contract changes shape; today only this revision exists.
+ */
+export const SITE_KIND = 'texuli.site/v1';
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const LANG_PATTERN = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+function fail(message) {
+    throw new TypeError(`Invalid Texuli site: ${message}`);
+}
+function text(value, field, max) {
+    if (typeof value !== 'string' || value.trim() === '')
+        fail(`${field} must be a non-empty string.`);
+    const trimmed = value.trim();
+    if (trimmed.length > max)
+        fail(`${field} must be at most ${max} characters.`);
+    return trimmed;
+}
+function optionalText(value, field, max) {
+    if (value === undefined)
+        return undefined;
+    return text(value, field, max);
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function normalizeBaseUrl(value) {
+    const raw = text(value, 'url', 2048);
+    // Site definitions are developer-authored, so the developer tier applies;
+    // the scheme check below still narrows to deployable http(s) origins.
+    const safe = safeHref(raw, 'developer');
+    if (safe === undefined)
+        fail('url must be a safe http(s) URL.');
+    let parsed;
+    try {
+        parsed = new URL(safe);
+    }
+    catch {
+        fail('url must be an absolute http(s) URL.');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        fail('url must use the https or http scheme.');
+    }
+    if (parsed.search !== '')
+        fail('url must not carry a query string.');
+    if (parsed.hash !== '')
+        fail('url must not carry a fragment.');
+    const base = `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}`;
+    return base;
+}
+function joinHref(base, path) {
+    return path === '/' ? `${base}/` : `${base}${path}`;
+}
+function validateBlocks(slug, value) {
+    const parsed = safeParseBlocks(value);
+    if (parsed.success)
+        return parsed.data;
+    const summarize = (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`;
+    const listed = parsed.issues.slice(0, 8).map(summarize).join('; ');
+    const more = parsed.issues.length > 8 ? ` (+${parsed.issues.length - 8} more)` : '';
+    fail(`page "${slug}" has invalid blocks — ${listed}${more}`);
+}
+function validatePage(input, base, seenSlugs) {
+    if (typeof input !== 'object' || input === null)
+        fail('every page must be an object.');
+    const slug = text(input.slug, 'page slug', 100);
+    if (!SLUG_PATTERN.test(slug)) {
+        fail(`page slug "${slug}" must be lowercase kebab-case (a-z, 0-9, dashes).`);
+    }
+    if (seenSlugs.has(slug))
+        fail(`page slug "${slug}" is duplicated.`);
+    seenSlugs.add(slug);
+    const title = text(input.title, `page "${slug}" title`, 200);
+    const description = optionalText(input.description, `page "${slug}" description`, 300);
+    const nav = optionalText(input.nav, `page "${slug}" nav label`, 120);
+    let updated;
+    if (input.updated !== undefined) {
+        updated = text(input.updated, `page "${slug}" updated`, 10);
+        if (!DATE_PATTERN.test(updated) || Number.isNaN(Date.parse(`${updated}T00:00:00Z`))) {
+            fail(`page "${slug}" updated must be an ISO calendar date (YYYY-MM-DD).`);
+        }
+    }
+    const home = input.home === true;
+    const path = home ? '/' : `/${slug}`;
+    return Object.freeze({
+        slug,
+        path,
+        title,
+        ...(description === undefined ? {} : { description }),
+        ...(updated === undefined ? {} : { updated }),
+        ...(nav === undefined ? {} : { nav }),
+        home,
+        href: joinHref(base, path),
+        blocks: validateBlocks(slug, input.blocks ?? []),
+    });
+}
+function deepFreezeSite(site) {
+    for (const page of site.pages)
+        Object.freeze(page);
+    Object.freeze(site.pages);
+    Object.freeze(site.navigation);
+    return Object.freeze(site);
+}
+/**
+ * Validate a static-site definition and return the frozen, normalized model
+ * that Protoyard `site` exports hand to the layouts, navigation and sitemap
+ * helpers. Throws a `TypeError` naming the offending field when any part of
+ * the closed schema fails: one home page, unique lowercase kebab-case slugs,
+ * an http(s) base URL without query or fragment, and page content that
+ * passes the closed Texuli block schema. Blocks are validated but never
+ * rendered here; painting them stays with the host's sink-free renderer.
+ */
+export function defineSite(input) {
+    if (typeof input !== 'object' || input === null)
+        fail('the site definition must be an object.');
+    if (input.kind !== undefined && input.kind !== SITE_KIND) {
+        fail(`kind must be "${SITE_KIND}" when present.`);
+    }
+    const name = text(input.name, 'name', 120);
+    const base = normalizeBaseUrl(input.url);
+    const lang = input.lang === undefined ? 'en' : text(input.lang, 'lang', 35);
+    if (!LANG_PATTERN.test(lang))
+        fail('lang must be a base language tag with optional subtags.');
+    if (!Array.isArray(input.pages))
+        fail('pages must be an array.');
+    if (input.pages.length === 0)
+        fail('a site needs at least one page.');
+    const seenSlugs = new Set();
+    const pages = input.pages.map((page) => validatePage(page, base, seenSlugs));
+    const homes = pages.filter((page) => page.home);
+    if (homes.length === 0)
+        fail('exactly one page must set home: true.');
+    if (homes.length > 1)
+        fail('only one page may set home: true.');
+    const navigation = pages
+        .filter((page) => page.nav !== undefined)
+        .map((page) => Object.freeze({ slug: page.slug, label: page.nav, href: page.href }));
+    return deepFreezeSite({ name, url: base, lang, pages, navigation });
+}
+/** Return the site's page for a slug, or `undefined` when absent. */
+export function sitePage(site, slug) {
+    return site.pages.find((page) => page.slug === slug);
+}
+/**
+ * Metadata for a page as ContentLayout props: the home page titles as the
+ * site name, others as `page title — site name`; the canonical is the
+ * page's absolute URL.
+ */
+export function sitePageMeta(site, slug) {
+    const page = sitePage(site, slug);
+    if (page === undefined)
+        return undefined;
+    return {
+        title: page.home ? site.name : `${page.title} — ${site.name}`,
+        ...(page.description === undefined ? {} : { description: page.description }),
+        canonical: page.href,
+        lang: site.lang,
+    };
+}
+/**
+ * Deterministic sitemap XML for the site: one entry per page in declared
+ * order, with `lastmod` only for pages that declare an `updated` date. The
+ * result is data for a `sitemap.xml` endpoint, never HTML.
+ */
+export function siteSitemap(site) {
+    const entries = site.pages
+        .map((page) => {
+        const lastmod = page.updated === undefined ? '' : `    <lastmod>${page.updated}</lastmod>\n`;
+        return `  <url>\n    <loc>${xmlEscape(page.href)}</loc>\n${lastmod}  </url>`;
+    })
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
+}

package/dist/styles.css

@@ -0,0 +1,36 @@
+@import "@texuli/tokens/base.css";
+@import "@texuli/tokens/forced-colors.css";
+
+/* Integration-selected variants override per-theme density and shape scales. */
+:root[data-tx-density="compact"] {
+  --tx-density: 0.875;
+}
+
+:root[data-tx-density="comfortable"] {
+  --tx-density: 1;
+}
+
+:root[data-tx-density="spacious"] {
+  --tx-density: 1.125;
+}
+
+:root[data-tx-radius="compact"] {
+  --tx-radius-scale: 0.75;
+}
+
+:root[data-tx-radius="comfortable"] {
+  --tx-radius-scale: 1;
+}
+
+:root[data-tx-radius="rounded"] {
+  --tx-radius-scale: 1.25;
+}
+
+@media print {
+  :root {
+    color-scheme: light;
+    --tx-motion: 0;
+    --tx-shadow: transparent;
+    print-color-adjust: economy;
+  }
+}

package/dist/styles.css.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@texuli/astro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.0",
+  "description": "Astro integration, content layouts and Svelte islands for Texuli sites.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./content": "./dist/content/index.js",
+    "./integration": "./dist/integration/index.js",
+    "./site": "./dist/site/index.js",
+    "./styles.css": {
+      "types": "./dist/styles.css.d.ts",
+      "default": "./dist/styles.css"
+    },
+    "./layouts/ContentLayout": "./dist/layouts/ContentLayout.js",
+    "./sections/Hero": "./dist/sections/Hero.js",
+    "./sections/Section": "./dist/sections/Section.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@texuli/blocks": "0.1.0-next.0",
+    "@texuli/core": "0.1.0-next.0",
+    "@texuli/tokens": "0.1.0-next.0",
+    "astro": "^7.4.0"
+  },
+  "peerDependencies": {
+    "@astrojs/svelte": "^9.1.0",
+    "svelte": "^5.57.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}