ampless 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/index.d.ts

@@ -69,7 +69,339 @@ declare function detectContentEvents(input: {
     newStatus?: 'draft' | 'published';
 }): ContentEventType[];
 
+type ThemeFieldType = 'color' | 'text' | 'select' | 'image' | 'length' | 'fontFamily' | 'linkList';
+/**
+ * Single entry in a `linkList` field. Stored as part of a JSON array
+ * under the field's storage key. `url` may be:
+ *  - a relative path (`/about`)
+ *  - an absolute URL (`https://example.com`)
+ *  - a tag reference (`tag:guide`) — themes interpret this as
+ *    "expand to a list of posts with this tag" rather than rendering
+ *    a literal link.
+ */
+interface LinkListItem {
+    label: string;
+    url: string;
+}
+/**
+ * A user-facing string in a manifest. Either a plain string (rendered
+ * as-is, regardless of locale) or a per-locale map (the renderer picks
+ * the active locale, falling back to `en`, then to any value).
+ *
+ * Themes that ship in a single language can keep these as plain
+ * strings. The default themes use the map form so the same manifest
+ * works for both built-in dictionaries.
+ */
+type LocalizedString = string | Record<string, string>;
+interface ThemeFieldBase {
+    /** Storage key. Persisted as `theme.{key}` in site settings. */
+    key: string;
+    label: LocalizedString;
+    description?: LocalizedString;
+    /** Optional UI grouping (e.g. 'Colors', 'Typography', 'Branding'). */
+    group?: LocalizedString;
+    /** Used when no override is set. Always a string for storage uniformity. */
+    default: string;
+    /**
+     * If set, the loader injects `${cssVar}: ${value}` into a `:root`
+     * style block on every public page, so CSS rules using
+     * `var(${cssVar})` pick up overrides at render time.
+     *
+     * Fields without `cssVar` (e.g. logo URL, header tagline) are exposed
+     * to template code via `loadThemeConfig()` instead.
+     */
+    cssVar?: string;
+}
+interface ThemeColorField extends ThemeFieldBase {
+    type: 'color';
+}
+interface ThemeTextField extends ThemeFieldBase {
+    type: 'text';
+    maxLength?: number;
+}
+interface ThemeSelectField extends ThemeFieldBase {
+    type: 'select';
+    options: ReadonlyArray<{
+        value: string;
+        label: LocalizedString;
+    }>;
+}
+interface ThemeImageField extends ThemeFieldBase {
+    type: 'image';
+}
+interface ThemeLengthField extends ThemeFieldBase {
+    type: 'length';
+}
+interface ThemeFontFamilyField extends ThemeFieldBase {
+    type: 'fontFamily';
+    options: ReadonlyArray<{
+        value: string;
+        label: LocalizedString;
+    }>;
+}
+/**
+ * A repeatable list of {label, url} entries — used for nav menus,
+ * footer link sets, sidebar groups, etc. Stored in KvStore as a JSON
+ * string so it fits the existing `string`-valued site-settings cache.
+ *
+ * `default` is declared as a plain array for ergonomics; the loader
+ * stringifies it on the fly so manifest authors don't have to call
+ * JSON.stringify by hand.
+ */
+interface ThemeLinkListField extends Omit<ThemeFieldBase, 'default' | 'cssVar'> {
+    type: 'linkList';
+    default: ReadonlyArray<LinkListItem>;
+    /** Cap admin-supplied list length. Default 50. */
+    maxItems?: number;
+}
+type ThemeField = ThemeColorField | ThemeTextField | ThemeSelectField | ThemeImageField | ThemeLengthField | ThemeFontFamilyField | ThemeLinkListField;
+interface ThemeManifest {
+    /** Theme directory name (`themes/<name>/`). */
+    name: string;
+    label: LocalizedString;
+    description?: LocalizedString;
+    fields: ReadonlyArray<ThemeField>;
+}
+declare function defineTheme(m: ThemeManifest): ThemeManifest;
+/**
+ * Resolve a `LocalizedString` to a plain string for display.
+ * Strings pass through; maps pick `locale` → `fallback` → any value
+ * → empty. The empty fallback keeps the renderer from crashing on a
+ * malformed manifest while making the missing translation visible.
+ */
+declare function resolveLocalized(value: LocalizedString | undefined, locale: string, fallback?: string): string;
+interface ThemeRouteContext<P = Record<string, string>> {
+    params: Promise<P>;
+}
+interface ThemeModule {
+    /** Stable identifier — must match the directory name and the value
+     *  stored as `theme.active`. */
+    name: string;
+    manifest: ThemeManifest;
+    /**
+     * Server components rendered by the dispatcher routes
+     * (`app/page.tsx`, `app/[slug]/page.tsx`, `app/tag/[tag]/page.tsx`).
+     * Each theme MUST provide Home; Post / Tag are recommended but
+     * optional (dispatcher 404s when missing).
+     */
+    components: {
+        Home: (ctx: ThemeRouteContext) => Promise<unknown> | unknown;
+        Post?: (ctx: ThemeRouteContext<{
+            slug: string;
+        }>) => Promise<unknown> | unknown;
+        Tag?: (ctx: ThemeRouteContext<{
+            tag: string;
+        }>) => Promise<unknown> | unknown;
+    };
+    /**
+     * Optional `generateMetadata` hooks called by the dispatcher. Same
+     * signature as the matching component's params.
+     */
+    metadata?: {
+        Home?: (ctx: ThemeRouteContext) => Promise<unknown> | unknown;
+        Post?: (ctx: ThemeRouteContext<{
+            slug: string;
+        }>) => Promise<unknown> | unknown;
+        Tag?: (ctx: ThemeRouteContext<{
+            tag: string;
+        }>) => Promise<unknown> | unknown;
+    };
+    /**
+     * Optional route handlers for /feed.xml and /sitemap.xml. The
+     * dispatcher returns 404 if a theme doesn't provide them.
+     */
+    routes?: {
+        feed?: (ctx: {
+            request: Request;
+        }) => Promise<Response>;
+        sitemap?: (ctx: {
+            request: Request;
+        }) => Promise<Response>;
+    };
+}
+declare function defineThemeModule(m: ThemeModule): ThemeModule;
+/**
+ * Storage key used in KvStore. Prefix `theme.` keeps the namespace
+ * separate from `site.*` / `media.*` so unrelated tools can scan
+ * settings without colliding.
+ */
+declare function themeSettingKey(fieldKey: string): string;
+/**
+ * Reject malformed or potentially-injectable values before they reach
+ * the KvStore. Admin/editor are trusted but typos and copy-paste
+ * mistakes shouldn't be able to break a site's CSS or sneak `</style>`
+ * into the inline tag the loader emits.
+ *
+ * Returns the normalized value, or null if the input is rejected.
+ */
+/**
+ * Split a stored color value into its light / dark components.
+ *
+ * Accepts two storage forms:
+ *   - Single value: `oklch(...)` / `#abcdef` / etc. → `{ light: value, dark: null }`
+ *   - Pair: `light-dark(L, D)` → `{ light: L, dark: D }`
+ *
+ * Splits on the top-level comma (depth-aware) so nested commas inside
+ * `rgb(...)` / `hsl(...)` don't trip the parser.
+ */
+declare function parseColorPair(value: string): {
+    light: string;
+    dark: string | null;
+};
+/**
+ * Build the storage string for a color field. When `dark` is non-empty
+ * and differs from `light`, returns `light-dark(light, dark)`; otherwise
+ * returns the bare `light` value. The runtime emits the result verbatim
+ * into the inline `:root { --foo: <value> }` override; `light-dark()`
+ * is a Baseline-2024 CSS function so the browser picks per mode.
+ */
+declare function formatColorPair(light: string, dark?: string | null): string;
+declare function validateThemeValue(field: ThemeField, raw: unknown): string | null;
+/** Parse a stored linkList JSON value into typed items. Tolerant: bad
+ *  shapes resolve to []. Throwing here would cascade into rendering. */
+declare function parseLinkList(raw: string | undefined | null): LinkListItem[];
+declare function stringifyLinkList(items: ReadonlyArray<LinkListItem>): string;
+/**
+ * Detect a `tag:<name>` URL form. Themes use this to render a list of
+ * posts under a heading instead of a literal link — useful for docs
+ * sidebars and category-style nav.
+ */
+declare function isTagListUrl(url: string): {
+    tag: string;
+} | null;
+/**
+ * Resolve effective values for every manifest field, merging stored
+ * overrides on top of defaults. `stored` is the flat settings map keyed
+ * by `theme.{key}` — typically the output of `listSiteSettings()`
+ * filtered to theme entries.
+ */
+declare function resolveThemeValues(manifest: ThemeManifest, stored: Record<string, unknown>): Record<string, string>;
+
 type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
+/**
+ * Plugin capability declarations. The runtime uses this list for
+ * declaration-vs-implementation reconciliation warnings and (in later
+ * phases) for `allowCapabilities` gating in `cms.config.ts`.
+ *
+ * Phase 1 active capabilities:
+ *   - `publicHead` / `publicBody`: descriptor-based head/body injection.
+ *   - `metadata` / `eventHooks`: name-only declaration for existing surfaces.
+ *
+ * Reserved capabilities are accepted by the type so that plugins can
+ * declare future intent, but the runtime does nothing with them yet —
+ * each has its own RFP under `docs/tmp/`. Declaring a reserved
+ * capability today is harmless, but the runtime won't expose any new
+ * surface for it until the matching phase ships.
+ */
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'schema' | 'writePublicAsset' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
+/**
+ * Loading strategy for `script` / `inlineScript` descriptors.
+ *
+ *   - `afterInteractive` (default): load after hydration, non-blocking.
+ *     The runtime adds `async` for external scripts when neither
+ *     `async` nor `defer` is set explicitly. `inlineScript` is emitted
+ *     inline as-is in Phase 1 (strategy is informational only for
+ *     inline; see comments in `plugin-head.ts`).
+ *   - `lazyOnload`: defer load further. Phase 1 maps this to `defer`
+ *     for external scripts; full lazy-load (next/script's idle
+ *     scheduling) is a future enhancement.
+ *
+ * `beforeInteractive` is intentionally excluded — App Router does not
+ * support emitting plain `<script>` elements that block hydration from
+ * the runtime layer, and the spec defers that case to the future
+ * developer extension surface.
+ */
+type ScriptStrategy = 'afterInteractive' | 'lazyOnload';
+/**
+ * Context passed to `publicHead` / `publicBodyEnd`. Phase 1 carries
+ * only the site-wide config block. Phase 2 adds the `setting()`
+ * accessor for admin-managed `settings.public` values; per-route /
+ * per-post context lands in Phase 4 (`plugin-per-post-rfp.md`).
+ */
+interface PluginPublicRenderContext {
+    site: Config['site'];
+    /**
+     * Resolve a public setting value for the active plugin instance.
+     * Returns `stored ?? manifest.default ?? undefined`. Stored values
+     * are read at request time from the DDB → S3 site-settings cache
+     * pipeline. Bound by the runtime when the plugin declares
+     * `settings.public` — plugins without a manifest can still call
+     * this, in which case it always returns `undefined`.
+     *
+     * The generic type is a convenience cast: the runtime does not
+     * coerce values, so callers should pick `T` to match the field's
+     * declared type (`text` → `string`, `number` → `number`, etc.).
+     * Validation at admin save time guarantees stored values match the
+     * field's declared shape, so the cast is safe in practice.
+     */
+    setting<T = unknown>(key: string): T | undefined;
+}
+/**
+ * Descriptor returned by `publicHead()`. The runtime validates each
+ * entry (URL scheme denylist, `attrs` allowlist, id collision handling)
+ * and renders the surviving descriptors as React elements inside the
+ * root layout's `<head>`. Returning arbitrary `ReactNode` is
+ * intentionally not offered here — see
+ * `docs/architecture/08-plugin-architecture.md` §"Descriptor-based
+ * Head/Body Injection".
+ */
+type PublicHeadDescriptor = {
+    type: 'script';
+    /** Element id; doubles as the duplicate-detection key. */
+    id?: string;
+    src: string;
+    strategy?: ScriptStrategy;
+    async?: boolean;
+    defer?: boolean;
+    /** Allow-listed attributes only (data-*, crossorigin, referrerpolicy, ...). */
+    attrs?: Record<string, string | boolean>;
+} | {
+    type: 'inlineScript';
+    /** Required for duplicate detection and dev warnings. */
+    id: string;
+    body: string;
+    strategy?: ScriptStrategy;
+    /**
+     * Type-only reservation. CSP nonce resolution (including the
+     * planned `'auto'` mode) is deferred to a future RFP; Phase 1
+     * does not propagate this field to the rendered element.
+     */
+    nonce?: string;
+} | {
+    type: 'meta';
+    name?: string;
+    property?: string;
+    content: string;
+} | {
+    type: 'link';
+    rel: string;
+    href: string;
+    as?: string;
+    /** Mapped to React's `type` attribute. */
+    typeAttr?: string;
+} | {
+    type: 'noscript';
+    id?: string;
+    /** Raw HTML emitted inside `<noscript>`. */
+    html: string;
+};
+/**
+ * Descriptor returned by `publicBodyEnd()`. Supports the same
+ * `script` / `inlineScript` / `noscript` variants as the head, plus
+ * the body-only `iframe` variant (used by Google Tag Manager's
+ * `<noscript>`-style fallback frame, chat widgets, etc.).
+ */
+type PublicBodyDescriptor = Extract<PublicHeadDescriptor, {
+    type: 'script' | 'inlineScript' | 'noscript';
+}> | {
+    type: 'iframe';
+    id?: string;
+    src: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    attrs?: Record<string, string | boolean>;
+};
 /**
  * Metadata-like object that maps cleanly onto Next.js `Metadata`. We keep
  * the shape framework-agnostic so the core type doesn't depend on Next.js.
@@ -156,11 +488,131 @@ interface OgImageConfig {
      */
     render(ctx: OgImageRenderContext): Promise<unknown> | unknown;
 }
+/**
+ * Shared shape for every `PluginSettingField` variant. `T` is the
+ * decoded value type (string for text-like fields, number for number,
+ * boolean for boolean, etc.). All variants share `key` / `label` /
+ * `default` / `required`; type-specific constraints (e.g. `pattern`,
+ * `min`, `options`) live on the discriminated branches.
+ */
+interface PluginFieldBase<T> {
+    /**
+     * Storage key. Stored as `plugins.<instanceId>.<key>`. Must match
+     * `PLUGIN_KEY_PATTERN` (`/^[a-zA-Z0-9_-]+$/`) so the `pk.sk` dotted
+     * separator survives. Violations are skipped + warned by the
+     * runtime/admin normalization pass.
+     */
+    key: string;
+    label: LocalizedString;
+    description?: LocalizedString;
+    /** Used by the runtime when no admin-stored value is present. */
+    default?: T;
+    /**
+     * When true, an empty / undefined value is rejected at save time
+     * and the resolver returns `undefined`. When false (default),
+     * string-like fields accept empty string as a valid "disabled"
+     * value while non-string fields still reject empty strings.
+     */
+    required?: boolean;
+    /** Optional UI grouping (mirrors `ThemeField.group`). */
+    group?: LocalizedString;
+}
+interface PluginTextField extends PluginFieldBase<string> {
+    type: 'text';
+    maxLength?: number;
+    /** RegExp source (e.g. `'^G-[A-Z0-9]+$'`). Validated against
+     *  non-empty values; empty string skips the check. */
+    pattern?: string;
+    /** Placeholder for the admin input. */
+    placeholder?: string;
+}
+interface PluginTextareaField extends PluginFieldBase<string> {
+    type: 'textarea';
+    maxLength?: number;
+    placeholder?: string;
+    /** Rendered rows hint for the admin textarea. */
+    rows?: number;
+}
+interface PluginBooleanField extends PluginFieldBase<boolean> {
+    type: 'boolean';
+}
+interface PluginNumberField extends PluginFieldBase<number> {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface PluginSelectField extends PluginFieldBase<string> {
+    type: 'select';
+    options: ReadonlyArray<{
+        value: string;
+        label: LocalizedString;
+    }>;
+}
+interface PluginUrlField extends PluginFieldBase<string> {
+    type: 'url';
+    placeholder?: string;
+    /** When true, relative paths (`/foo`, `./foo`) pass validation; default true. */
+    allowRelative?: boolean;
+}
+interface PluginCodeField extends PluginFieldBase<string> {
+    type: 'code';
+    /** Display-only language label (e.g. `'js'`, `'css'`, `'html'`). */
+    language?: string;
+    maxLength?: number;
+    placeholder?: string;
+    rows?: number;
+}
+interface PluginJsonField extends PluginFieldBase<unknown> {
+    type: 'json';
+    placeholder?: string;
+    rows?: number;
+}
+type PluginSettingField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField | PluginCodeField | PluginJsonField;
+/**
+ * Per-plugin settings declaration. Phase 2 implements `public`;
+ * `secret` is reserved for Phase 6a (admin-only storage; never reaches
+ * the public runtime).
+ */
+interface PluginSettingsManifest {
+    public?: readonly PluginSettingField[];
+}
 interface AmplessPlugin {
     name: string;
     /** Plugin API version. Currently 1; future versions will be additive. */
     apiVersion: 1;
     trust_level: TrustLevel;
+    /**
+     * Stable per-install namespace. Defaults to `name` when omitted.
+     * Distinguishes multiple instances of the same plugin (e.g. two GTM
+     * containers, two GA4 measurement IDs). Multi-instance run-time
+     * validation lands in Phase 3; Phase 1 only adds the field so plugin
+     * authors can author against it now.
+     */
+    instanceId?: string;
+    /**
+     * Human-readable label for admin UI surfaces (Phase 2 onward).
+     * Plain string or per-locale map — see `LocalizedString`.
+     */
+    displayName?: LocalizedString;
+    /**
+     * Declared capability list. The runtime uses this for
+     * declaration-vs-implementation warnings (e.g. a plugin that
+     * declares `publicBody` but defines no `publicBodyEnd`); later
+     * phases will gate dangerous capabilities through `cms.config.ts`
+     * `allowCapabilities`. Existing plugins that omit this field
+     * continue to work unchanged.
+     */
+    capabilities?: readonly PluginCapability[];
+    /**
+     * Public, admin-editable settings (Phase 2). Each declared field is
+     * stored under `pk='siteconfig', sk='plugins.<instanceId>.<key>'`,
+     * mirrored to S3 via the trusted processor, and surfaced to
+     * `publicHead` / `publicBodyEnd` via `ctx.setting<T>(key)`. Plugins
+     * without an admin UI continue to work — they just don't have a
+     * `settings` block.
+     */
+    settings?: PluginSettingsManifest;
     /** Async event hooks. Run in trust_level-matched Lambda. */
     hooks?: {
         [K in EventType]?: PluginEventHandler<K>;
@@ -174,6 +626,20 @@ interface AmplessPlugin {
      * Site-level metadata (root layout). Returned per request.
      */
     siteMetadata?(site: Config['site']): PluginMetadata;
+    /**
+     * Declarative head injection. Returns a list of validated
+     * descriptors (script / inlineScript / meta / link / noscript). The
+     * runtime collects every plugin's contribution at render time, runs
+     * URL scheme + attrs validation, then emits React elements inside
+     * the root layout's `<head>`. See `PublicHeadDescriptor`.
+     */
+    publicHead?(ctx: PluginPublicRenderContext): readonly PublicHeadDescriptor[];
+    /**
+     * Same shape as `publicHead`, but the result is appended at the
+     * end of `<body>` and additionally supports the `iframe` variant
+     * (GTM no-script fallback frame, chat widgets, ...).
+     */
+    publicBodyEnd?(ctx: PluginPublicRenderContext): readonly PublicBodyDescriptor[];
     /**
      * Dynamic OG image renderer. The dispatcher route (e.g.
      * `app/og/[slug]/route.ts`) reads this and feeds the element into
@@ -560,6 +1026,53 @@ declare function decodeAwsJson(value: unknown): unknown;
  */
 declare function formatPublicAssetUrl(bucket: string, region: string, key: string): string;
 
+declare const PLUGIN_KEY_PATTERN: RegExp;
+declare function isValidPluginKey(key: string): boolean;
+/**
+ * Validate one raw value against a field definition. Returns the
+ * (possibly-coerced) value on success, or `null` to signal rejection.
+ *
+ * Semantics:
+ *   - **string-like fields** (text / textarea / url / code) accept
+ *     `''` as valid when `required` is falsy. This is the "disable"
+ *     sentinel — e.g. `pattern: '^$|^G-...'` lets a GA4 plugin save
+ *     an empty measurementId to suppress the loader without dropping
+ *     the row.
+ *   - **non-string-like fields** (number / boolean / json / select)
+ *     always reject `''`. Allowing it would force callers to handle a
+ *     `string` reading where `number | undefined` is declared. To
+ *     "unset" these fields, delete the row (admin form's "Reset to
+ *     default" button).
+ *   - `undefined` is treated as "not set" by `resolvePluginSettings`
+ *     — `validatePluginSettingValue` itself returns `null` for it.
+ *   - Constraints (`pattern`, `min`, `max`, `maxLength`, `options`) run
+ *     only when the value is present and non-empty.
+ *
+ * The returned shape preserves the declared type — `text` stores a
+ * sanitized string, `number` stores a `number`, `boolean` stores a
+ * `boolean`, `json` stores the decoded value (object / array /
+ * primitive — never the source string), etc.
+ */
+declare function validatePluginSettingValue(field: PluginSettingField, raw: unknown): unknown | null;
+/**
+ * Merge stored values on top of manifest defaults for one plugin
+ * instance. Both sides are validated through `validatePluginSettingValue`
+ * — stored values that fail validation (manual DDB tampering, schema
+ * drift) fall back to the validated default; defaults that themselves
+ * fail validation surface as `undefined`.
+ *
+ * `stored` is a flat key → value map keyed by the field's `key` (not
+ * the full DDB SK). The runtime extracts it from the site-settings
+ * snapshot using the `plugins.<instanceId>.` prefix.
+ *
+ * Validation runs on the default too because the default can come
+ * from a plugin's constructor argument (e.g. GA4 takes a
+ * `measurementId` option and passes it through as the field's
+ * `default`). If the operator supplies a bogus value at install time
+ * we'd rather surface `undefined` than render garbage.
+ */
+declare function resolvePluginSettings(manifest: PluginSettingsManifest | undefined, stored: Record<string, unknown>): Record<string, unknown>;
+
 /**
  * Extract the first image URL from a post body. Used by plugins (e.g.
  * plugin-og-image) that want to derive an image from the post content
@@ -663,214 +1176,6 @@ declare function pickDefaultEntrypoint(files: readonly {
     path: string;
 }[]): string;
 
-type ThemeFieldType = 'color' | 'text' | 'select' | 'image' | 'length' | 'fontFamily' | 'linkList';
-/**
- * Single entry in a `linkList` field. Stored as part of a JSON array
- * under the field's storage key. `url` may be:
- *  - a relative path (`/about`)
- *  - an absolute URL (`https://example.com`)
- *  - a tag reference (`tag:guide`) — themes interpret this as
- *    "expand to a list of posts with this tag" rather than rendering
- *    a literal link.
- */
-interface LinkListItem {
-    label: string;
-    url: string;
-}
-/**
- * A user-facing string in a manifest. Either a plain string (rendered
- * as-is, regardless of locale) or a per-locale map (the renderer picks
- * the active locale, falling back to `en`, then to any value).
- *
- * Themes that ship in a single language can keep these as plain
- * strings. The default themes use the map form so the same manifest
- * works for both built-in dictionaries.
- */
-type LocalizedString = string | Record<string, string>;
-interface ThemeFieldBase {
-    /** Storage key. Persisted as `theme.{key}` in site settings. */
-    key: string;
-    label: LocalizedString;
-    description?: LocalizedString;
-    /** Optional UI grouping (e.g. 'Colors', 'Typography', 'Branding'). */
-    group?: LocalizedString;
-    /** Used when no override is set. Always a string for storage uniformity. */
-    default: string;
-    /**
-     * If set, the loader injects `${cssVar}: ${value}` into a `:root`
-     * style block on every public page, so CSS rules using
-     * `var(${cssVar})` pick up overrides at render time.
-     *
-     * Fields without `cssVar` (e.g. logo URL, header tagline) are exposed
-     * to template code via `loadThemeConfig()` instead.
-     */
-    cssVar?: string;
-}
-interface ThemeColorField extends ThemeFieldBase {
-    type: 'color';
-}
-interface ThemeTextField extends ThemeFieldBase {
-    type: 'text';
-    maxLength?: number;
-}
-interface ThemeSelectField extends ThemeFieldBase {
-    type: 'select';
-    options: ReadonlyArray<{
-        value: string;
-        label: LocalizedString;
-    }>;
-}
-interface ThemeImageField extends ThemeFieldBase {
-    type: 'image';
-}
-interface ThemeLengthField extends ThemeFieldBase {
-    type: 'length';
-}
-interface ThemeFontFamilyField extends ThemeFieldBase {
-    type: 'fontFamily';
-    options: ReadonlyArray<{
-        value: string;
-        label: LocalizedString;
-    }>;
-}
-/**
- * A repeatable list of {label, url} entries — used for nav menus,
- * footer link sets, sidebar groups, etc. Stored in KvStore as a JSON
- * string so it fits the existing `string`-valued site-settings cache.
- *
- * `default` is declared as a plain array for ergonomics; the loader
- * stringifies it on the fly so manifest authors don't have to call
- * JSON.stringify by hand.
- */
-interface ThemeLinkListField extends Omit<ThemeFieldBase, 'default' | 'cssVar'> {
-    type: 'linkList';
-    default: ReadonlyArray<LinkListItem>;
-    /** Cap admin-supplied list length. Default 50. */
-    maxItems?: number;
-}
-type ThemeField = ThemeColorField | ThemeTextField | ThemeSelectField | ThemeImageField | ThemeLengthField | ThemeFontFamilyField | ThemeLinkListField;
-interface ThemeManifest {
-    /** Theme directory name (`themes/<name>/`). */
-    name: string;
-    label: LocalizedString;
-    description?: LocalizedString;
-    fields: ReadonlyArray<ThemeField>;
-}
-declare function defineTheme(m: ThemeManifest): ThemeManifest;
-/**
- * Resolve a `LocalizedString` to a plain string for display.
- * Strings pass through; maps pick `locale` → `fallback` → any value
- * → empty. The empty fallback keeps the renderer from crashing on a
- * malformed manifest while making the missing translation visible.
- */
-declare function resolveLocalized(value: LocalizedString | undefined, locale: string, fallback?: string): string;
-interface ThemeRouteContext<P = Record<string, string>> {
-    params: Promise<P>;
-}
-interface ThemeModule {
-    /** Stable identifier — must match the directory name and the value
-     *  stored as `theme.active`. */
-    name: string;
-    manifest: ThemeManifest;
-    /**
-     * Server components rendered by the dispatcher routes
-     * (`app/page.tsx`, `app/[slug]/page.tsx`, `app/tag/[tag]/page.tsx`).
-     * Each theme MUST provide Home; Post / Tag are recommended but
-     * optional (dispatcher 404s when missing).
-     */
-    components: {
-        Home: (ctx: ThemeRouteContext) => Promise<unknown> | unknown;
-        Post?: (ctx: ThemeRouteContext<{
-            slug: string;
-        }>) => Promise<unknown> | unknown;
-        Tag?: (ctx: ThemeRouteContext<{
-            tag: string;
-        }>) => Promise<unknown> | unknown;
-    };
-    /**
-     * Optional `generateMetadata` hooks called by the dispatcher. Same
-     * signature as the matching component's params.
-     */
-    metadata?: {
-        Home?: (ctx: ThemeRouteContext) => Promise<unknown> | unknown;
-        Post?: (ctx: ThemeRouteContext<{
-            slug: string;
-        }>) => Promise<unknown> | unknown;
-        Tag?: (ctx: ThemeRouteContext<{
-            tag: string;
-        }>) => Promise<unknown> | unknown;
-    };
-    /**
-     * Optional route handlers for /feed.xml and /sitemap.xml. The
-     * dispatcher returns 404 if a theme doesn't provide them.
-     */
-    routes?: {
-        feed?: (ctx: {
-            request: Request;
-        }) => Promise<Response>;
-        sitemap?: (ctx: {
-            request: Request;
-        }) => Promise<Response>;
-    };
-}
-declare function defineThemeModule(m: ThemeModule): ThemeModule;
-/**
- * Storage key used in KvStore. Prefix `theme.` keeps the namespace
- * separate from `site.*` / `media.*` so unrelated tools can scan
- * settings without colliding.
- */
-declare function themeSettingKey(fieldKey: string): string;
-/**
- * Reject malformed or potentially-injectable values before they reach
- * the KvStore. Admin/editor are trusted but typos and copy-paste
- * mistakes shouldn't be able to break a site's CSS or sneak `</style>`
- * into the inline tag the loader emits.
- *
- * Returns the normalized value, or null if the input is rejected.
- */
-/**
- * Split a stored color value into its light / dark components.
- *
- * Accepts two storage forms:
- *   - Single value: `oklch(...)` / `#abcdef` / etc. → `{ light: value, dark: null }`
- *   - Pair: `light-dark(L, D)` → `{ light: L, dark: D }`
- *
- * Splits on the top-level comma (depth-aware) so nested commas inside
- * `rgb(...)` / `hsl(...)` don't trip the parser.
- */
-declare function parseColorPair(value: string): {
-    light: string;
-    dark: string | null;
-};
-/**
- * Build the storage string for a color field. When `dark` is non-empty
- * and differs from `light`, returns `light-dark(light, dark)`; otherwise
- * returns the bare `light` value. The runtime emits the result verbatim
- * into the inline `:root { --foo: <value> }` override; `light-dark()`
- * is a Baseline-2024 CSS function so the browser picks per mode.
- */
-declare function formatColorPair(light: string, dark?: string | null): string;
-declare function validateThemeValue(field: ThemeField, raw: unknown): string | null;
-/** Parse a stored linkList JSON value into typed items. Tolerant: bad
- *  shapes resolve to []. Throwing here would cascade into rendering. */
-declare function parseLinkList(raw: string | undefined | null): LinkListItem[];
-declare function stringifyLinkList(items: ReadonlyArray<LinkListItem>): string;
-/**
- * Detect a `tag:<name>` URL form. Themes use this to render a list of
- * posts under a heading instead of a literal link — useful for docs
- * sidebars and category-style nav.
- */
-declare function isTagListUrl(url: string): {
-    tag: string;
-} | null;
-/**
- * Resolve effective values for every manifest field, merging stored
- * overrides on top of defaults. `stored` is the flat settings map keyed
- * by `theme.{key}` — typically the output of `listSiteSettings()`
- * filtered to theme entries.
- */
-declare function resolveThemeValues(manifest: ThemeManifest, stored: Record<string, unknown>): Record<string, string>;
-
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, type Page, type PluginEventHandler, type PluginMetadata, type PluginRuntimeContext, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type Role, SITE_CONFIG_PK, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPublicRenderContext, type PluginRuntimeContext, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validateThemeValue };