ampless 1.0.0-alpha.15 → 1.0.0-alpha.17

package/dist/index.d.ts

@@ -69,7 +69,325 @@ 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; per-route and per-post context lands
+ * in Phase 4 (`plugin-per-post-rfp.md`). Plugin settings are read from
+ * the factory closure today — Phase 2 (`plugin-settings-rfp.md`) adds
+ * an admin-managed accessor here.
+ */
+interface PluginPublicRenderContext {
+    site: Config['site'];
+}
+/**
+ * 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.
@@ -161,6 +479,28 @@ interface AmplessPlugin {
     /** 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[];
     /** Async event hooks. Run in trust_level-matched Lambda. */
     hooks?: {
         [K in EventType]?: PluginEventHandler<K>;
@@ -174,6 +514,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
@@ -246,9 +600,33 @@ type CacheStrategy = 'auto' | 'deep' | 'hot';
  * are free to store their own per-post state here (e.g. SEO overrides,
  * feature flags, A/B variants).
  */
+/**
+ * Per-file metadata recorded on a static post. The static route
+ * reads this to decide whether to stream the bytes back through
+ * Lambda (small files → cached by CloudFront) or to 302-redirect
+ * to a presigned URL (large files → bypass the Lambda response
+ * size envelope). Populated by `upload_static_bundle` /
+ * `commit_static_post` at upload time so the read path never
+ * issues a HEAD round-trip.
+ *
+ * `body.files` (the manifest's flat list) stays the source of truth
+ * for "what's in the bundle"; this map is purely a delivery hint and
+ * may be sparse when older bundles predate the migration.
+ */
+interface StaticPostFileMeta {
+    size: number;
+    mimeType: string;
+}
 interface PostMetadata {
     no_layout?: boolean;
     cache?: CacheStrategy;
+    /**
+     * For `format: 'static'` posts only. Keyed by the bundle-relative
+     * path (same shape as `body.files` entries). Older bundles may
+     * lack this map — readers MUST treat a missing entry as
+     * "fall back to a HEAD lookup".
+     */
+    files?: Record<string, StaticPostFileMeta>;
     [key: string]: unknown;
 }
 interface Post {
@@ -281,12 +659,25 @@ interface Page {
     status: PostStatus;
     publishedAt?: string;
 }
+/**
+ * Asset metadata recorded on the Media row. Currently the only
+ * well-known key is `etag` (the S3 object ETag, captured at upload
+ * time so the media-proxy route can emit it back to the client
+ * without a HEAD round-trip). Free-form by design — themes and
+ * plugins can add their own keys (image dimensions, EXIF strip
+ * status, etc.) without a schema change.
+ */
+interface MediaMetadata {
+    etag?: string;
+    [key: string]: unknown;
+}
 interface Media {
     mediaId: string;
     src: string;
     mimeType: string;
     size: number;
     delivery: 'nextjs' | 's3-direct';
+    metadata?: MediaMetadata;
 }
 type ImageDisplay = 'inline' | 'lightbox';
 /**
@@ -500,9 +891,8 @@ declare function escapeXml(s: string): string;
  *     from DynamoDB (the path used by the trusted processor and the
  *     MCP Lambda).
  *
- * `decodeAwsJson` tolerates both: pass strings through `JSON.parse`,
- * everything else as-is, fall back to the raw string on parse errors
- * so bare-string rows aren't lost.
+ * `decodeAwsJson` handles both: pass strings through `JSON.parse`,
+ * everything else as-is.
  */
 /**
  * Serialise a value for an AWSJSON variable. `undefined` / `null` both
@@ -513,7 +903,7 @@ declare function encodeAwsJson(value: unknown): string;
 /**
  * Deserialise an AWSJSON value from a GraphQL / DynamoDB read.
  * Tolerates both the wire-string shape and the auto-unmarshalled
- * native value. Returns the raw string when `JSON.parse` rejects it.
+ * native value. Throws if the string is not valid JSON.
  */
 declare function decodeAwsJson(value: unknown): unknown;
 
@@ -627,214 +1017,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 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 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, type Page, type PluginCapability, type PluginEventHandler, type PluginMetadata, type PluginPublicRenderContext, type PluginRuntimeContext, 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, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validateThemeValue };

package/dist/index.js

@@ -202,11 +202,7 @@ function encodeAwsJson(value) {
 }
 function decodeAwsJson(value) {
   if (typeof value !== "string") return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
+  return JSON.parse(value);
 }
 
 // src/storage.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",