ampless 1.0.0-alpha.9 → 1.0.0-beta.52

package/dist/index.d.ts

@@ -1,7 +1,22 @@
+import { ReactNode } from 'react';
+
 type ContentEventType = 'content.created' | 'content.updated' | 'content.published' | 'content.unpublished' | 'content.deleted';
 type MediaEventType = 'media.uploaded' | 'media.deleted';
 type SiteSettingsEventType = 'site.settings.updated';
-type EventType = ContentEventType | MediaEventType | SiteSettingsEventType;
+/**
+ * Emitted on every Post mutation (INSERT / MODIFY / REMOVE) with both
+ * the previous and the next projection of the row. Drives index-style
+ * derivation: the built-in trusted-processor handler uses it to keep
+ * the `PostTag` denormalized index in sync without making every write
+ * path (admin, MCP, future REST clients) remember to call a helper.
+ *
+ * Plugins that maintain their own indexes (custom search, sitemaps
+ * with per-tag pages, etc.) can subscribe through the same hook
+ * surface as the other event types — the diff payload is already in
+ * the right shape for "compute add/remove/update".
+ */
+type PostIndexEventType = 'post.index.refresh';
+type EventType = ContentEventType | MediaEventType | SiteSettingsEventType | PostIndexEventType;
 /** Minimal projection of a Post item carried in events (no body, to keep payloads small). */
 interface ContentEventPayload {
     postId: string;
@@ -23,7 +38,17 @@ interface MediaEventPayload {
  */
 interface SiteSettingsEventPayload {
 }
-type EventPayloadOf<T extends EventType> = T extends ContentEventType ? ContentEventPayload : T extends MediaEventType ? MediaEventPayload : T extends SiteSettingsEventType ? SiteSettingsEventPayload : never;
+/**
+ * Diff payload for `post.index.refresh`. `previous` is null on INSERT;
+ * `next` is null on REMOVE; both populated on MODIFY. Subscribers
+ * compute the add / remove / update set from this — see the trusted
+ * processor's `rebuildPostTags` handler for the canonical example.
+ */
+interface PostIndexEventPayload {
+    previous: ContentEventPayload | null;
+    next: ContentEventPayload | null;
+}
+type EventPayloadOf<T extends EventType> = T extends ContentEventType ? ContentEventPayload : T extends MediaEventType ? MediaEventPayload : T extends SiteSettingsEventType ? SiteSettingsEventPayload : T extends PostIndexEventType ? PostIndexEventPayload : never;
 interface AmplessEvent<T extends EventType = EventType> {
     type: T;
     payload: EventPayloadOf<T>;
@@ -46,7 +71,479 @@ 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`.
+ *
+ * Active capabilities:
+ *   - `publicHead` / `publicBody`: descriptor-based head/body injection.
+ *   - `metadata` / `eventHooks`: name-only declaration for existing surfaces.
+ *   - `adminSettings`: admin-managed public settings manifest.
+ *   - `writePublicAsset`: trusted hook context can write namespaced public assets.
+ *   - `schema`: per-post body injection via `publicBodyForPost`,
+ *     scoped to JSON-LD `<script type="application/ld+json">`. Themes
+ *     render the descriptors by calling `ampless.publicBodyForPost(post)`
+ *     in their post template.
+ *   - `secretSettings`: admin-managed secret settings stored in the isolated
+ *     `PluginSecret` DynamoDB model. Requires `trust_level: 'trusted'`.
+ *     Trusted hooks access secrets via `ctx.secret<T>(key)`.
+ *
+   * Reserved capabilities are accepted by the type so that plugins can
+   * declare future intent, but the runtime does nothing with them yet.
+   * 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' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'secretSettings' | 'contentFields' | 'publicPostScript' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem' | 'cspReady';
+/**
+ * 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;
+    /**
+     * Request-scoped CSP nonce reservation. Always `undefined` in Phase 1
+     * — the runtime does not populate this field yet. Middleware/SSR
+     * threading lands with the future CSP RFP. Plugin authors who want to
+     * be ready for the future stamping can declare
+     * `inlineScript.nonce: 'auto'` today; once the middleware-driven
+     * threading PR lands, those descriptors will become candidates for
+     * runtime nonce stamping.
+     */
+    cspNonce?: string;
+}
+/**
+ * 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>;
+    /**
+     * Optional CSP nonce. Same semantics as inlineScript.nonce
+     * (`'auto'` is the sentinel for future runtime stamping; any
+     * other string is an explicit literal; undefined emits no
+     * `nonce` attribute). Phase 1 reservation: runtime accepts
+     * but does not propagate. See `inlineScript.nonce` JSDoc for
+     * the full description.
+     */
+    nonce?: 'auto' | string;
+} | {
+    type: 'inlineScript';
+    /** Required for duplicate detection and dev warnings. */
+    id: string;
+    body: string;
+    strategy?: ScriptStrategy;
+    /**
+     * Optional MIME-like script type. Phase 4 allows
+     * `'application/ld+json'` only — when set, the runtime emits
+     * `<script type="application/ld+json">` and **auto-escapes** the
+     * `body` (`<`, `>`, `&`, U+2028, U+2029 → `\uXXXX`) so plugin
+     * authors cannot accidentally let a value break out of the
+     * script tag. This invariant is applied across all three
+     * surfaces (`publicHead` / `publicBodyEnd` / `publicBodyForPost`).
+     *
+     * Unsupported values are dropped (descriptor and warning).
+     * Surface-dependent strictness:
+     *   - `publicHead` / `publicBodyEnd`: `undefined` (= default JS,
+     *     backwards compatible) or `'application/ld+json'`.
+     *   - `publicBodyForPost`: `'application/ld+json'` REQUIRED —
+     *     the per-post body surface is scoped to JSON-LD only so
+     *     the schema capability does not become a per-post arbitrary
+     *     inline-JS channel. A future capability would open that
+     *     explicitly.
+     */
+    scriptType?: 'application/ld+json';
+    /**
+     * Optional CSP nonce.
+     *
+     *   - `'auto'`: sentinel reserved for future runtime stamping.
+     *     When the middleware/SSR CSP nonce threading PR lands, the
+     *     runtime will read `ctx.cspNonce` from the request scope
+     *     and stamp the rendered `<script>` tag automatically.
+     *   - any other `string`: explicit nonce literal (advanced;
+     *     rarely needed).
+     *   - `undefined`: no `nonce` attribute emitted (default,
+     *     backward-compatible with non-CSP sites).
+     *
+     * Phase 1 reservation: the runtime accepts the field but does
+     * not propagate it to the rendered element. Declaring
+     * `nonce: 'auto'` today is a forward-compatibility hint and
+     * does not change the rendered HTML.
+     *
+     * Note: TypeScript does not type-widen here — `string` already
+     * accepts `'auto'` as a literal. The semantic reservation is
+     * documented above.
+     */
+    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>` via React's
+     * `dangerouslySetInnerHTML`. This is an intentional escape hatch:
+     * descriptors otherwise constrain shape (typed props on `meta` /
+     * `link` / `script`), but `<noscript>` content is often vendor-
+     * supplied (analytics fallbacks, etc.) and cannot be modelled
+     * as typed props without an unbounded discriminated union.
+     *
+     * **Trust model.** This is part of the same public injection
+     * surface as `inlineScript` and `script`. It is **not** gated
+     * by the plugin's `trust_level` — `untrusted` plugins can emit
+     * a `noscript` descriptor too, and the runtime tests in
+     * `packages/runtime/src/plugin-head.test.ts` explicitly cover
+     * the untrusted case. The trust decision is **plugin install**:
+     * an admin installs a plugin, accepting whatever it eventually
+     * renders into `<head>` / `<body>`. The boundary is structurally
+     * the same as the [editor trust
+     * model](../../docs/architecture/04-access-layer-mcp.md#editor-trust-model-specification)
+     * — editors can already inject arbitrary `<script>` via post
+     * body anyway, so a per-plugin sandbox here wouldn't change the
+     * upper bound. If a tighter sandbox is needed, scope it at
+     * install time: do not install plugins you do not trust to
+     * render arbitrary HTML into your pages.
+     *
+     * **Author guidance.** Plugin authors are still responsible
+     * for the HTML being well-formed — in particular, do not embed
+     * `</noscript>` sequences mid-content (such a sequence breaks
+     * out of the element and the remainder of the string is parsed
+     * as page-level HTML). The runtime does not detect or mask
+     * this; the regression test in
+     * [`packages/runtime/src/plugin-head.test.ts`](../../packages/runtime/src/plugin-head.test.ts)
+     * pins the current passthrough behaviour so any future move
+     * to sanitization becomes a deliberate, reviewed change.
+     */
+    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>;
+};
+/**
+ * Descriptor returned by `publicBodyForPost()` (Phase 4). Limited to
+ * the `inlineScript` variant with `scriptType: 'application/ld+json'`
+ * REQUIRED. This narrowing is deliberate:
+ *   - The per-post body surface is for JSON-LD / structured data only.
+ *     We do not want the `schema` capability to become a per-post
+ *     arbitrary inline-JS channel.
+ *   - `meta` / `link` belong in `<head>`; theme post pages render
+ *     these descriptors inside `<body>`, so meta/link are excluded.
+ *
+ * If a future use case needs per-post arbitrary inline JS (e.g.
+ * Microsoft Clarity per-page tagging), open it through a new
+ * capability such as `publicPostScript` rather than relaxing this.
+ */
+type PublicPostBodyDescriptor = Extract<PublicHeadDescriptor, {
+    type: 'inlineScript';
+}> & {
+    /** Required for `publicBodyForPost`; the runtime drops any descriptor
+     *  whose scriptType is not 'application/ld+json'. */
+    scriptType: 'application/ld+json';
+};
+/**
+ * Slot positions for `publicHtmlForPost` descriptors. v1 ships two
+ * fixed slots; additional slots (beforeTitle / sidebar / etc) are
+ * deferred until dogfood reveals the need.
+ */
+type PublicPostHtmlPosition = 'beforeContent' | 'afterContent';
+/**
+ * Per-post visible HTML descriptor returned by `publicHtmlForPost`.
+ * The runtime sanitizes `body` with `sanitize-html` under a strict
+ * allowlist before rendering; see the plugin-author guide for how
+ * trusted plugins compose with the public surface.
+ *
+ * `id` is a plugin-local short identifier (e.g. `'display'`). The
+ * runtime resolves it to `${instanceId ?? name}:${id}` when building
+ * the React wrapper key — plugin authors do not embed their own
+ * namespace in `id`.
+ */
+interface PublicPostHtmlDescriptor {
+    type: 'html';
+    id: string;
+    body: string;
+    position: PublicPostHtmlPosition;
+}
 /**
  * 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.
@@ -79,7 +576,48 @@ interface PluginMetadata {
         types?: Record<string, string>;
     };
 }
-type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void>;
+/**
+ * Hook return value reservation (Phase 1: type only, runtime no-op).
+ *
+ * Today's runtime (after-event SQS Lambdas) ignores the return value
+ * entirely. The type is widened so a future PR can land additive
+ * directives without breaking plugin authors who publish in the
+ * meantime. Likely first use case:
+ *
+ *   - `metrics?: Record<string, number>` — emit observability data
+ *     without touching CloudWatch SDK directly from the plugin.
+ *
+ * `cancel` / `post` rewrite-style directives are NOT enabled by this
+ * type alone — they would also require `before:*` events to be wired
+ * to plugins (currently reserved, see events.ts) and payload shapes
+ * to expose mutable bodies. This PR widens the return surface only;
+ * richer semantics need follow-on PRs.
+ *
+ * The `readonly __amplessPluginHookResult?: never` marker is a
+ * type-level nominal tag: it prevents `Promise<void | PluginHookResult>`
+ * from silently accepting unrelated promise types like
+ * `Promise<string>` or `Promise<number>`. Plugin authors do not need
+ * to set this field — it is optional and exists only to constrain
+ * what the union accepts.
+ */
+interface PluginHookResult {
+    readonly __amplessPluginHookResult?: never;
+}
+/**
+ * Async event hook handler.
+ *
+ * The return value is reserved (see `PluginHookResult`). Today's
+ * runtime ignores it — returning `undefined` (`Promise<void>`) is
+ * the canonical "no-op" and matches existing plugin code without
+ * migration. Plugins that explicitly return a `PluginHookResult`
+ * object type-check today but do not change runtime behaviour
+ * until the matching capability PR lands.
+ *
+ * Non-PluginHookResult promise types (`Promise<string>`,
+ * `Promise<number>`, etc.) are rejected at compile time by the
+ * `__amplessPluginHookResult` private marker on `PluginHookResult`.
+ */
+type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void | PluginHookResult>;
 /**
  * Runtime services injected into hook handlers by the Lambda processor.
  * Decoupling plugins from concrete AWS clients lets us swap implementations
@@ -96,6 +634,57 @@ interface PluginRuntimeContext {
      */
     writePublicAsset(key: string, body: string | Uint8Array, contentType: string): Promise<string>;
 }
+/**
+ * Context passed to the `uninstall` lifecycle hook (Phase 1
+ * reservation: runtime no-op — see `AmplessPlugin.uninstall`).
+ *
+ * Phase 1: structurally identical to `PluginRuntimeContext`. The
+ * dedicated type exists so future cleanup helpers
+ * (`deletePublicAsset`, `deletePluginSetting`, `deletePluginSecret`)
+ * can be added here without exposing them to regular event hooks,
+ * which take `PluginRuntimeContext` and should not be able to
+ * delete state from arbitrary plugin areas.
+ *
+ * Phase 1 scope is limited to: (a) reserving the type name, (b)
+ * reserving the hook signature `(ctx: PluginUninstallContext) =>
+ * Promise<void>`. Cleanup helper methods are NOT included in
+ * Phase 1 — plugin authors writing `await ctx.deletePublicAsset(...)`
+ * today would hit a TS error. The actual cleanup body lands when
+ * the future lifecycle-dispatch PR adds the helper methods to this
+ * type (additive, no breaking change for plugins that declared an
+ * empty `uninstall` body in advance).
+ */
+interface PluginUninstallContext extends PluginRuntimeContext {
+}
+/**
+ * Extended runtime context for **trusted** hook handlers. Adds
+ * `secret<T>(key)` — an async accessor that reads from the isolated
+ * `PluginSecret` DynamoDB model (which admin / editor groups cannot
+ * query). The result is per-invocation cached to avoid redundant DDB
+ * calls when the same key is read multiple times inside one hook batch.
+ *
+ * Cache key is `${instanceId ?? name}:${fieldKey}` to prevent
+ * cross-plugin collisions when two plugin instances declare the same
+ * `key` (e.g. both have a `'signingSecret'` field).
+ *
+ * Only available in the trusted processor (`processor-trusted.ts`).
+ * The untrusted processor never constructs a `TrustedPluginRuntimeContext`
+ * — untrusted hook handlers receive plain `PluginRuntimeContext`, which
+ * does not expose `secret`.
+ */
+interface TrustedPluginRuntimeContext extends PluginRuntimeContext {
+    /**
+     * Read a secret value stored under the plugin's namespace in the
+     * `PluginSecret` table. Returns `undefined` when no value has been
+     * saved yet. The generic `T` is a convenience cast (same pattern as
+     * `ctx.setting<T>()`) — values are always stored as strings, so `T`
+     * defaults to `string`.
+     *
+     * Per-invocation cached: calling `ctx.secret('key')` twice within
+     * the same SQS batch hit costs one DDB round-trip.
+     */
+    secret<T = string>(key: string): Promise<T | undefined>;
+}
 /**
  * A font registered with a plugin's OG image renderer. Satori (the engine
  * inside Next.js `ImageResponse`) requires at least one font. We accept
@@ -133,15 +722,532 @@ 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;
+}
+/**
+ * Sub-fields allowed inside a `PluginRepeatableField`. Restricted to
+ * the scalar-shape field types so the v1 admin editor can render each
+ * cell with the existing `renderScalarInput` seam. Code / json /
+ * repeatable are excluded — code is rarely useful per-item, json
+ * recurses into "json inside json" UX that we explicitly want to
+ * avoid, and nested repeatable is deferred.
+ */
+type PluginRepeatableSubField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField;
+interface PluginRepeatableField extends PluginFieldBase<ReadonlyArray<Readonly<Record<string, unknown>>>> {
+    type: 'repeatable';
+    /** Shape of each item — every item is a flat object keyed by sub-field `key`. */
+    fields: ReadonlyArray<PluginRepeatableSubField>;
+    /** Hard cap on item count (default 50). Exceeding rejects the whole field. */
+    maxItems?: number;
+    /** Minimum item count (default 0). Below rejects the whole field. */
+    minItems?: number;
+    /** Label for the "+ Add item" button in the admin editor. */
+    addLabel?: LocalizedString;
+    /**
+     * Sub-field key used as the per-item heading in the admin editor
+     * (e.g. `'id'` so categories[0] reads "analytics" not "Item 1").
+     * Falls back to "Item N" when absent or empty.
+     */
+    itemLabelKey?: string;
+}
+type PluginSettingField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField | PluginCodeField | PluginJsonField | PluginRepeatableField;
+/**
+ * Static manifest declared in a plugin package's `package.json` under
+ * the `amplessPlugin` key. The plugin package must also expose
+ * `package.json` itself via `exports`:
+ *
+ *   "exports": {
+ *     ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+ *     "./package.json": "./package.json"
+ *   }
+ *
+ * Without the subpath export, Node's package-exports gating rejects
+ * `import.meta.resolve('<pkg>/package.json')` and the runtime cannot
+ * load the manifest. Without `amplessPlugin`, the runtime skips
+ * cross-check silently and falls back to the existing per-factory
+ * capability mismatch checks (backward compatible).
+ */
+interface PluginPackageManifest {
+    /** Must match `AmplessPlugin.apiVersion`. Mismatch throws at runtime
+     *  to prevent loading a plugin built against a different ampless API. */
+    apiVersion: 1;
+    /** Should match `AmplessPlugin.name`. Mismatch warns. */
+    name: string;
+    /** Should match `AmplessPlugin.trust_level`. Mismatch warns. */
+    trustLevel: TrustLevel;
+    /** Should match `AmplessPlugin.capabilities`. Disagreement warns. */
+    capabilities: readonly PluginCapability[];
+    /** Optional admin UI label. */
+    displayName?: LocalizedString;
+    /** Optional short description (1 line). */
+    description?: LocalizedString;
+    /** Optional docs / repo URL. */
+    homepage?: string;
+    /**
+     * Subpath (relative to the plugin's package.json) of the editor
+     * module to auto-wire. `update-ampless` reads this to regenerate
+     * `app/(admin)/admin/_editor-bootstrap.tsx`. Absent = no editor
+     * extension (= plugin doesn't ship a tiptap Node).
+     *
+     * The referenced module must export `editorExtension` as a named
+     * symbol of type tiptap Extension.
+     */
+    editorExports?: string;
+}
+/**
+ * Secret field types for `settings.secret`. Restricted to `text` /
+ * `textarea` — the only types useful for opaque string secrets
+ * (API keys, signing secrets, SMTP passwords). More complex types
+ * (number, boolean, select, repeatable) are excluded: structured
+ * secrets are out of scope for v1.
+ *
+ * The `default` property is intentionally stripped via `Omit`. If it
+ * were allowed, the default value would propagate into the admin form
+ * props (visible in the browser), static manifests cross-checked by
+ * the runtime, and JS bundles — multiple leak paths for a value that
+ * must stay server-side. Plugin authors that have a constructor-time
+ * fallback value should keep it as a **closure-private variable** that
+ * is never exposed in the manifest (see the plugin author guide for
+ * the "closure-private fallback" pattern).
+ */
+type PluginSecretField = Omit<PluginTextField, 'default'> | Omit<PluginTextareaField, 'default'>;
+/**
+ * Per-plugin settings declaration. Phase 2 implements `public`;
+ * Phase 6a adds `secret` (admin-only storage; never reaches the public
+ * runtime or S3 mirror).
+ */
+interface PluginSettingsManifest {
+    public?: readonly PluginSettingField[];
+    /**
+     * Admin-managed secret settings. Values are stored in the isolated
+     * `PluginSecret` DynamoDB model, which has no `read` authorization
+     * for admin / editor groups — only trusted Lambda IAM can read them.
+     * Secrets never reach the public runtime or the S3 site-settings
+     * mirror. Requires `trust_level: 'trusted'` and the
+     * `'secretSettings'` capability. Declaring this with an untrusted
+     * plugin throws at `definePlugin()` time; declaring it without the
+     * capability warns.
+     */
+    secret?: readonly PluginSecretField[];
+    /**
+     * Optional manifest shape version (Phase 1 reservation: runtime
+     * no-op).
+     *
+     * Plugin authors bump this integer when they change the shape of
+     * `public` or `secret` field arrays in a way that today's
+     * write/read paths cannot transparently absorb — i.e. when a field
+     * is renamed, when a field's `type` changes incompatibly, or when
+     * a field's semantic meaning shifts (same key + same type but the
+     * value should be re-interpreted).
+     *
+     * **Phase 1 scope**: the field is type-only. The runtime does NOT
+     * read it today, does NOT persist it next to stored values, and
+     * does NOT trigger any migration. Today's behaviour around shape
+     * changes continues to apply, but it differs between `public` and
+     * `secret` because the two travel through entirely different
+     * write/read paths:
+     *
+     *   - `settings.public` goes through `resolvePluginSettings`
+     *     (`packages/ampless/src/plugin-settings.ts`), which iterates
+     *     `manifest.public` and falls back to `field.default` per
+     *     field. So for public fields, additions resolve via `default`,
+     *     deletions become orphan KvStore rows that the resolver
+     *     silently skips, and incompatible type changes fall through
+     *     to `default` when the stored value fails validation.
+     *   - `settings.secret` is never read by `resolvePluginSettings`.
+     *     The admin UI writes individual values through the
+     *     `setPluginSecret` AppSync mutation; trusted hooks read them
+     *     individually by key via `ctx.secret<T>(key)` which goes
+     *     directly to the `PluginSecret` DynamoDB table. There is no
+     *     `manifest.default` fallback for secrets (the type forbids
+     *     `default` on secret fields). Additions show up in the admin
+     *     UI when the manifest changes; removals leave the stored
+     *     ciphertext row orphaned (no resolver runs over it); renames
+     *     and type changes mean the old key's stored row is never
+     *     read again until an operator deletes it manually.
+     *
+     * None of these paths produce a signal to the plugin author.
+     *
+     * **Future migration PR**: may persist the active manifest
+     * version somewhere alongside stored values and may compare it
+     * to `manifest.version` at resolve time to detect mismatch. The
+     * exact storage location, comparison timing, and mismatch
+     * response are all design territory for that future PR — this
+     * reservation fixes the field name and type on the manifest,
+     * nothing more.
+     *
+     * Important scope distinction: this reservation covers the
+     * `version` *field name and type* on `PluginSettingsManifest`
+     * only. The actual migration mechanism (a `migrate` hook, an
+     * admin-driven flow, batch resolve-time-rewrite, etc.) is a
+     * separate design that lands with its own PR. Declaring
+     * `version` today does NOT pre-wire a migration body — when the
+     * future migration PR ships, plugins that want to provide a
+     * migration body will need to re-publish to add it. Existing
+     * plugins that omit `version` are unaffected by this addition;
+     * plugins that want to participate in the future migration
+     * detection path can opt in today by declaring `version: 1`,
+     * instead of having to re-publish later just to add the
+     * version declaration once the migration PR ships. The
+     * migration body itself (and any future `migrate` hook
+     * signature) is NOT reserved by this PR.
+     *
+     * Recommended values: positive integer, start at 1. Declare
+     * `version: 1` when the manifest first gains a `version` field,
+     * then bump by 1 on each shape-breaking release. Do NOT use
+     * `0` / negative numbers / floats — the `number` type accepts
+     * them but the semantics for those values are reserved for the
+     * future migration PR (`0` may be conflated with "no version
+     * declared" / legacy / pre-v1). Skip the field entirely if you
+     * do not care about migration support (the default, current
+     * behaviour).
+     */
+    version?: number;
+}
+/**
+ * Minimal tiptap node shape passed to a `contentFields` `tiptap` renderer.
+ * Mirrors the structural fields plugins typically read (`type`, `attrs`,
+ * `content`, `marks`, `text`) without coupling to a specific tiptap
+ * version. Plugins should treat unknown fields conservatively.
+ */
+interface TiptapRenderNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: readonly TiptapRenderNode[];
+    marks?: readonly {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    text?: string;
+}
+/**
+ * Adapter that converts a single tiptap node back to its markdown form.
+ * Plugins that ship an embed node (e.g. amplessYoutube → bare YouTube URL)
+ * export a map from nodeType to adapter from their `./editor` module
+ * (named export `tiptapNodeToMarkdown`); `update-ampless` wires the map
+ * into `installAdminTiptapNodeMarkdown` so the admin's
+ * `tiptap → markdown` format switch can losslessly serialise the embed
+ * (the round-trip back to tiptap goes through markdown's bare-URL paste
+ * rule + `extractSingleUrl` in the runtime).
+ *
+ * Return `null` (or simply omit the nodeType from the map) to fall
+ * through to the runtime's default markdown switch.
+ */
+type TiptapNodeToMarkdown = (node: TiptapRenderNode) => string | null;
+type TiptapNodeMarkdownAdapters = Readonly<Record<string, TiptapNodeToMarkdown>>;
+/**
+ * Adapter that converts a single tiptap node to its canonical HTML placeholder
+ * div form. Plugins that ship an embed node (e.g. amplessYoutube →
+ * `<div data-ampless-youtube data-video-id="...">…</div>`) export a map from
+ * nodeType to adapter from their `./editor` module (named export
+ * `tiptapNodeToHtml`); `update-ampless` wires the map into
+ * `installAdminTiptapNodeHtml` so the admin's `tiptap → html` format switch
+ * can losslessly serialise the embed to the canonical placeholder div form.
+ *
+ * The canonical div is what tiptap's `Node.renderHTML` emits and what the
+ * `Node.parseHTML` `tag: 'div[data-ampless-*]'` rule restores from. It is an
+ * admin format-switch interchange form; public rendering expands embeds from
+ * the `tiptap` / `markdown` walkers, while `format: 'html'` preserves the div
+ * literally.
+ *
+ * The `markdown → html` direction is a 2-hop via `generateJSON(...)` so
+ * plugins only need to export the `tiptap → html` adapter; the markdown side
+ * reuses it via tiptap's parseHTML rules (no duplicate logic).
+ *
+ * Return `null` (or simply omit the nodeType from the map) to fall through to
+ * the runtime's default HTML switch.
+ */
+type TiptapNodeToHtml = (node: TiptapRenderNode) => string | null;
+type TiptapNodeHtmlAdapters = Readonly<Record<string, TiptapNodeToHtml>>;
+/**
+ * Match object passed to a `contentFields` `markdown-url` renderer. The
+ * runtime walks the markdown body via `marked.lexer`, tests the trimmed
+ * single-line URL of each `paragraph` token against the registered
+ * pattern, and on match calls `render({ match, raw }, ctx)` so the
+ * plugin can extract capture groups (e.g. the YouTube video id) and
+ * return a ReactNode for that paragraph.
+ */
+interface MarkdownEmbedMatch {
+    match: RegExpMatchArray;
+    raw: string;
+}
+/**
+ * Renderer registered via `AmplessPlugin.contentFields`. Two variants:
+ *
+ * - `tiptap`: keyed by `nodeType` (e.g. `'amplessYoutube'`). The runtime
+ *   walks tiptap docs and, when the walker encounters a node whose
+ *   `type` matches `nodeType`, calls `render(node, ctx)` to produce a
+ *   ReactNode in place of the default switch-based HTML emission.
+ *
+ * - `markdown-url`: keyed by a fully-anchored `RegExp` (the pattern
+ *   should use `^...$`). The runtime tokenizes markdown via
+ *   `marked.lexer`, looks for `paragraph` tokens whose entire content
+ *   is a single URL (autolink / bare URL / `[text](url)` with matching
+ *   text), tests the URL against `pattern`, and on match calls
+ *   `render({ match, raw }, ctx)` for that paragraph.
+ *
+ * Each `nodeType` / `pattern.source` may be registered by at most one
+ * plugin — duplicate registration throws at `createPluginHead` time.
+ */
+type ContentFieldRenderer = {
+    kind: 'tiptap';
+    nodeType: string;
+    render(node: TiptapRenderNode, ctx: PluginPublicRenderContext): ReactNode;
+    /**
+     * Opt-in: expand this node's canonical placeholder div when it
+     * appears in a `format: 'html'` post body on public render.
+     *
+     * The admin's `tiptap → html` format switch serialises an embed
+     * node (e.g. `amplessYoutube`) to its canonical placeholder div
+     * (`<div data-ampless-youtube data-video-id="…"><a href="…">…</a></div>`,
+     * via the `tiptapNodeToHtml` adapter). Without `htmlPlaceholder`,
+     * the public renderer of a `format: 'html'` post emits that div
+     * literally — the placeholder shows as a bare div + link instead
+     * of the live embed. (This was the documented limitation from the
+     * canonical-html-embed work; declaring `htmlPlaceholder` resolves
+     * it.)
+     *
+     * When declared, the runtime's public html walker finds each
+     * **top-level** element carrying `flagAttr`, builds a
+     * `TiptapRenderNode { type: nodeType, attrs: attrsFromElement(attribs) }`,
+     * and calls this same `render` — so the `tiptap`, `markdown`, and
+     * `html` formats all reach one renderer (no per-format divergence).
+     *
+     * - `flagAttr` is the marker attribute (e.g.
+     *   `'data-ampless-youtube'`). It is **matched case-insensitively**:
+     *   the runtime lowercases it at registration because htmlparser2
+     *   lowercases HTML attribute names while parsing, so declaring
+     *   `'data-My-Embed'` still matches `<div data-my-embed>` /
+     *   `<div DATA-MY-EMBED>`.
+     * - `attrsFromElement` converts the div's HTML attributes (already
+     *   lowercased by the parser) into the tiptap node `attrs` that
+     *   `render` expects, with the correct types — e.g. a
+     *   `data-start="30"` string must become the `number 30` that
+     *   `render` reads.
+     *
+     * Only top-level placeholders expand; divs nested inside
+     * `<blockquote>` / `<li>` / etc. stay literal. If `attrsFromElement`
+     * or `render` throws, the runtime warns and falls back to the raw
+     * placeholder slice (the embedded link stays clickable) rather than
+     * dropping the engineer-authored content.
+     */
+    htmlPlaceholder?: {
+        flagAttr: string;
+        attrsFromElement(attribs: Readonly<Record<string, string>>): Record<string, unknown>;
+    };
+} | {
+    kind: 'markdown-url';
+    pattern: RegExp;
+    render(m: MarkdownEmbedMatch, ctx: PluginPublicRenderContext): ReactNode;
+};
+/**
+ * Descriptor returned by `AmplessPlugin.publicPostScript(post, ctx)`.
+ * The runtime aggregates descriptors across every post passed to
+ * `ampless.publicPostScriptsForPage(posts)` and emits each unique `id`
+ * once as `<script src={src} async defer />`.
+ *
+ * `id` must be a stable, plugin-defined identifier (e.g.
+ * `'amplessTweet:widgets'`). Multiple posts on the same page that all
+ * need the same script collapse into a single tag.
+ *
+ * `src` must be an absolute `http://` or `https://` URL — relative
+ * paths and other schemes are dropped with a warning.
+ */
+interface PublicPostScriptDescriptor {
+    id: string;
+    src: string;
+    async?: boolean;
+    defer?: boolean;
+}
 interface AmplessPlugin {
     name: string;
-    /** Plugin API version. Currently 1; future versions will be additive. */
+    /**
+     * Plugin API version. Currently `1` is the only supported value.
+     * `apiVersion` is the breaking-change marker on the plugin contract;
+     * additive changes (new optional fields, new reserved capabilities)
+     * stay within `apiVersion: 1`. See the apiVersion bump policy in
+     * `docs/architecture/08-plugin-architecture.md` for the full criteria.
+     */
     apiVersion: 1;
+    /**
+     * Optional npm package name (e.g. `'@scope/ampless-plugin-foo'` or
+     * `'ampless-plugin-foo'`). When set, the runtime resolves
+     * `<packageName>/package.json` at `createPluginHead` construction
+     * time and cross-checks the static `amplessPlugin` manifest against
+     * the factory return value (`apiVersion` mismatch throws,
+     * `name` / `trustLevel` / `capabilities` mismatch warns).
+     *
+     * Plugins that omit this field — site-local plugins, first-party
+     * plugins predating Phase 5, etc. — skip cross-check entirely and
+     * fall back to the existing per-factory capability mismatch checks.
+     * Backward compatible: existing plugins continue to work unchanged.
+     *
+     * For external `npm publish` plugins, `packageName` MUST match the
+     * package's actual `name` and the package's `exports` MUST expose
+     * `./package.json`. The scaffold tool (`npx create-ampless@beta plugin`)
+     * handles both automatically.
+     */
+    packageName?: string;
     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>;
     };
+    /**
+     * Lifecycle hook called when this plugin is removed from
+     * `cms.config.ts` (Phase 1 reservation: runtime no-op).
+     *
+     * Today the runtime does not detect plugin removal and does not
+     * invoke this hook — orphan data left behind by an uninstalled
+     * plugin must be cleaned up manually by the operator. A future
+     * lifecycle-dispatch PR will need to solve the underlying
+     * problem that a plugin that has been deleted from `cms.config.ts`
+     * no longer has a callable factory in memory — `Config.plugins`
+     * (see `packages/ampless/src/types.ts`) only carries currently-
+     * active plugin objects. Possible future approaches:
+     *
+     *   - Two-stage `cms.config.ts` flag — `{ plugin: myPlugin(), pendingRemoval: true }`
+     *     keeps the plugin loadable while the runtime calls `uninstall`,
+     *     then the operator removes the entry once cleanup succeeds.
+     *   - Explicit `npx ampless uninstall <name>` CLI command — keeps
+     *     the plugin imported during the call by reading the prior
+     *     `cms.config.ts` entry, fires `uninstall`, then mutates the
+     *     file.
+     *   - Persist prior manifest + `packageName` to DDB/disk so the
+     *     runtime can `await import(packageName)` to re-acquire the
+     *     factory — assumes the npm package is still installed.
+     *
+     * The exact mechanism is deferred to the lifecycle-dispatch PR.
+     * What this reservation locks in: when `uninstall` does fire,
+     * it runs in a trusted-Lambda IAM context with cleanup grants for
+     * the five plugin-owned data areas (see
+     * docs/architecture/08-plugin-architecture.md
+     * §"Plugin-owned data areas"). Idempotency is the plugin author's
+     * responsibility — the hook may be invoked more than once
+     * (SQS at-least-once or operator-retry).
+     *
+     * **Phase 1 reservation scope**: only the hook name and signature
+     * are reserved. The ctx does NOT yet carry cleanup helpers
+     * (`deletePublicAsset` / `deletePluginSetting` /
+     * `deletePluginSecret`) — writing `await ctx.deletePublicAsset(...)`
+     * today is a TS error. The recommended Phase 1 declaration is an
+     * **empty body** (`async (_ctx) => {}`); the actual cleanup body
+     * lands when the lifecycle-dispatch PR adds the helpers. Plugins
+     * that declared the empty-body uninstall today will pick up the
+     * cleanup invocation events without re-publishing for the signature
+     * change, but a re-publish is required to add the actual cleanup
+     * body.
+     */
+    uninstall?: (ctx: PluginUninstallContext) => Promise<void>;
     /**
      * Per-post metadata generator. Pure function, called from Next.js
      * generateMetadata(). Must not have side effects.
@@ -151,6 +1257,101 @@ 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[];
+    /**
+     * Per-post body descriptors (Phase 4). Themes render the result by
+     * calling `ampless.publicBodyForPost(post)` in their post template;
+     * the descriptors emit inside `<body>` (not `<head>`, which the
+     * Next.js Metadata API cannot do for `<script>` tags). Primary use
+     * case: JSON-LD `<script type="application/ld+json">` Article
+     * schema. Restricted to inline-script descriptors with
+     * `scriptType: 'application/ld+json'` — see
+     * `PublicPostBodyDescriptor` for the rationale.
+     *
+     * The runtime auto-escapes `<`, `>`, `&`, U+2028, and U+2029 in the
+     * body so plugin authors cannot accidentally let a value break out
+     * of the script tag. The same escape is applied to any
+     * `'application/ld+json'` descriptor returned from `publicHead` or
+     * `publicBodyEnd`.
+     *
+     * Theme integration: first-party themes (blog / corporate / dads /
+     * docs / landing / minimal) all render the result automatically.
+     * Plugin authors who target custom themes should document the
+     * theme-side render call in their plugin's README — when the theme
+     * does not call `publicBodyForPost`, the plugin silently no-ops.
+     *
+     * Plugins implementing this should declare the `schema` capability.
+     */
+    publicBodyForPost?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostBodyDescriptor[];
+    /**
+     * Per-post visible HTML descriptors (Phase 6d). Themes render the
+     * result by calling `ampless.publicHtmlForPost(post)` in their post
+     * template; descriptors emit inside `<body>` at the `beforeContent`
+     * or `afterContent` slot relative to the post prose. Primary use
+     * cases: reading-time badge, breadcrumb, share links, micro-format
+     * annotations.
+     *
+     * Each descriptor's `body` is sanitized by the runtime under a
+     * strict `sanitize-html` allowlist before rendering — plugin authors
+     * may NOT call `dangerouslySetInnerHTML` themselves. The runtime
+     * wraps each surviving entry in a keyed `<div>` with the sanitized
+     * HTML.
+     *
+     * Plugin-local `id` (e.g. `'display'`) is namespace-resolved to
+     * `${instanceId ?? name}:${id}` by the runtime. Plugin authors do
+     * not embed their own namespace in `id`.
+     *
+     * Plugins implementing this should declare the `'publicHtmlForPost'`
+     * capability.
+     */
+    publicHtmlForPost?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostHtmlDescriptor[];
+    /**
+     * In-body content renderers (Phase 7 `contentFields` capability).
+     * Plugins register tiptap node renderers (keyed by `nodeType`) and/or
+     * markdown URL renderers (keyed by `RegExp`) here. The runtime walks
+     * post bodies during `ampless.renderBody(post)` and, on match, calls
+     * the renderer to obtain a `ReactNode` for that fragment in place of
+     * the default HTML output.
+     *
+     * Duplicate `nodeType` / `pattern.source` across plugins throws at
+     * `createPluginHead` construction time (eager config-time error). v1
+     * does not support multi-instance plugins registering the same
+     * renderer twice.
+     *
+     * Plugins implementing this should declare the `'contentFields'`
+     * capability.
+     */
+    contentFields?: readonly ContentFieldRenderer[];
+    /**
+     * Page-level script descriptors (Phase 7 `publicPostScript`
+     * capability). Themes call `ampless.publicPostScriptsForPage(posts)`
+     * after rendering post body / featured body; the runtime invokes
+     * `publicPostScript(post, ctx)` for each plugin × post pair, collects
+     * the descriptors, dedupes by `id`, and emits each unique entry as
+     * `<script src={src} async defer />`.
+     *
+     * Primary use case: x.com (Twitter) `widgets.js` to hydrate
+     * `<blockquote class="twitter-tweet">` blocks emitted by
+     * `contentFields`. YouTube embeds don't need this (the iframe loads
+     * its own script).
+     *
+     * Plugins implementing this should declare the `'publicPostScript'`
+     * capability.
+     */
+    publicPostScript?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostScriptDescriptor[];
     /**
      * Dynamic OG image renderer. The dispatcher route (e.g.
      * `app/og/[slug]/route.ts`) reads this and feeds the element into
@@ -188,6 +1389,22 @@ interface StaticPostBody {
     uploadedAt: string;
 }
 type PostStatus = 'draft' | 'published';
+/**
+ * Per-post cache strategy. Middleware computes the response's
+ * Cache-Control header from this value (plus `post.updatedAt` for the
+ * `auto` case and the project's `cms.config.cache.*` knobs).
+ *
+ *   - `'auto'` (default): cooldown by edit time. Posts updated within
+ *     the cooldown window (`cms.config.cache.cooldownMs`, default 1h)
+ *     emit a no-store header so editors see fresh content immediately.
+ *     Older posts emit a long s-maxage so the CDN serves them cheaply.
+ *   - `'deep'`: always long-cache (`cms.config.cache.deepTtlSeconds`,
+ *     default 1h). Use for posts whose content is fixed for the
+ *     foreseeable future.
+ *   - `'hot'`: always no-store. Use for posts whose content is rapidly
+ *     evolving or computed per request.
+ */
+type CacheStrategy = 'auto' | 'deep' | 'hot';
 /**
  * Free-form per-post metadata. The `metadata` JSON column carries
  * arbitrary key/value pairs; the runtime / themes / plugins each pick
@@ -196,16 +1413,44 @@ type PostStatus = 'draft' | 'published';
  *
  * Well-known keys:
  *   - `no_layout`: when true, the public page is served as bare HTML
- *     (no theme chrome). The runtime's post dispatcher checks this
- *     before rendering and redirects to the unified `/_/<slug>` route
- *     handler.
+ *     (no theme chrome). Middleware rewrites the request to the
+ *     internal `/raw/<slug>` handler for such posts and renders the
+ *     body verbatim — no Next.js root layout, no theme chrome.
+ *   - `cache`: see `CacheStrategy`. Overrides the default 'auto'
+ *     cache strategy for this post. Independent of `no_layout` —
+ *     applies uniformly to themed, no_layout, and static posts.
  *
  * Additional keys are passed through unchanged — themes and plugins
  * 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 {
@@ -219,6 +1464,15 @@ interface Post {
     publishedAt?: string;
     tags?: string[];
     metadata?: PostMetadata;
+    /**
+     * DynamoDB auto-managed timestamp (ISO 8601). Surfaced through the
+     * `PublicPost` projection so middleware can compute the
+     * `metadata.cache='auto'` cooldown without re-fetching the model
+     * row. Absent on optimistically-constructed posts (e.g. test
+     * fixtures); the cache strategy treats absent values as "very old"
+     * and emits a long s-maxage.
+     */
+    updatedAt?: string;
 }
 interface Page {
     pageId: string;
@@ -229,12 +1483,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';
 /**
@@ -288,11 +1555,61 @@ interface Config {
     locale?: string;
     /**
      * Active plugins. Each entry is the result of a plugin factory call
-     * (e.g. `seoPlugin({ ... })`) or a raw AmplessPlugin object. Strings are
-     * accepted for backward compatibility with the legacy v0 config but are
-     * ignored by the runtime.
+     * (e.g. `seoPlugin({ ... })`) or a raw AmplessPlugin object. Strings
+     * are accepted by the type for tolerance but are ignored by the
+     * runtime — only factory results and plugin objects take effect.
      */
     plugins?: Array<AmplessPlugin | string>;
+    /**
+     * Cache strategy knobs read by the runtime's middleware when
+     * computing `Cache-Control` for post responses. Each field is
+     * optional — middleware applies the documented defaults when a
+     * field is absent.
+     */
+    cache?: CacheConfig;
+    /**
+     * Post revision-history knobs. The event-dispatcher Lambda snapshots
+     * each post save into the `PostHistory` table; this controls how long
+     * those snapshots are retained.
+     */
+    history?: HistoryConfig;
+}
+/**
+ * Tunables for middleware-computed `Cache-Control`. See
+ * `PostMetadata.cache` / `CacheStrategy` for how the per-post override
+ * interacts with these defaults.
+ */
+interface CacheConfig {
+    /**
+     * `cache: 'auto'` cooldown. Posts whose `updatedAt` is younger than
+     * this many milliseconds emit a no-store header so editors see
+     * fresh content immediately after a save. Default 3,600,000 (1h).
+     */
+    cooldownMs?: number;
+    /**
+     * `cache: 'auto'` post-cooldown TTL, in seconds. Applied as both
+     * `max-age` and `s-maxage` on the response. Default 300 (5 minutes).
+     */
+    freshTtlSeconds?: number;
+    /**
+     * `cache: 'deep'` TTL, in seconds. Applied as both `max-age` and
+     * `s-maxage`. Default 3600 (1 hour).
+     */
+    deepTtlSeconds?: number;
+}
+/**
+ * Post revision-history tunables, read by the event-dispatcher Lambda
+ * (via the template shell) when snapshotting each post save.
+ */
+interface HistoryConfig {
+    /**
+     * Days to retain each post revision before DynamoDB TTL deletes it.
+     * Default 0 = keep forever (no `ttl` attribute is written). DynamoDB TTL
+     * deletes within ~48h after expiry, so effective retention is
+     * retentionDays + up to ~2 days. Changing this only affects revisions
+     * written afterward — existing rows keep their original expiry.
+     */
+    retentionDays?: number;
 }
 type Role = 'reader' | 'editor' | 'admin';
 interface AuthContext {
@@ -315,15 +1632,82 @@ interface ContentTypeDefinition {
     label: string;
     fields: Record<string, FieldDefinition>;
 }
-declare function defineSchema<T extends Record<string, ContentTypeDefinition>>(schema: T): T;
-
-interface ListOptions {
+declare function defineSchema<T extends Record<string, ContentTypeDefinition>>(schema: T): T;
+
+interface ListOptions {
+    limit?: number;
+    status?: 'draft' | 'published' | 'all';
+}
+type CreatePostInput = Omit<Post, 'postId'> & {
+    postId?: string;
+};
+/**
+ * One in-memory snapshot of a Post at save time, read back from the
+ * `PostHistory` table (written by the event-dispatcher Lambda on each
+ * Post INSERT/MODIFY — see packages/backend/src/events/dispatcher.ts).
+ *
+ * `body` is already decoded from its AWSJSON wire form (the provider
+ * runs `decodeAwsJson` before handing the row up), so it matches the
+ * `Post['body']` shape for the declared `format`.
+ */
+interface PostRevision {
+    /** Deterministic id `${postId}#${revisedAt}` — unique per save. */
+    postHistoryId: string;
+    postId: string;
+    /** ISO 8601 save time. Also the `byPost` GSI sort key (newest-first). */
+    revisedAt: string;
+    title?: string;
+    slug?: string;
+    excerpt?: string;
+    format?: ContentFormat;
+    body?: unknown;
+    status?: PostStatus;
+    publishedAt?: string;
+    tags?: string[];
+    metadata?: PostMetadata;
+}
+/** Pagination options for `listPostHistory`. */
+interface ListPostHistoryOptions {
     limit?: number;
+    nextToken?: string;
+}
+/**
+ * A page of revisions newest-first. `nextToken` feeds straight back into
+ * `ListPostHistoryOptions.nextToken` for the next page; `undefined` means
+ * no more rows.
+ */
+interface PostRevisionConnection {
+    items: PostRevision[];
+    nextToken?: string;
+}
+/**
+ * Lightweight row for admin list views — excludes body / metadata.
+ * Body fields (tiptap JSON, markdown source, etc.) can be tens of KB per post;
+ * projecting them out cuts per-post transfer size by 90%+ at scale.
+ *
+ * For list views that only need title / slug / status / dates / tags,
+ * use `listPostSummaries` instead of `listPosts`.
+ *
+ * Scale note: for single-site blogs (hundreds to low thousands of posts),
+ * full client-side fetch + sort/search is fast and eliminates GSI complexity.
+ * If a site grows to many thousands of posts, revisit with a
+ * (status, updatedAt) GSI + server-side pagination.
+ */
+interface PostSummary {
+    postId: string;
+    slug: string;
+    title: string;
+    excerpt?: string;
+    status: 'draft' | 'published';
+    publishedAt?: string;
+    updatedAt?: string;
+    tags: string[];
+}
+/** Options for `listPostSummaries`. */
+interface SummaryListOptions {
+    /** default 'all' */
     status?: 'draft' | 'published' | 'all';
 }
-type CreatePostInput = Omit<Post, 'postId'> & {
-    postId?: string;
-};
 interface PostsProvider {
     list(opts?: ListOptions): Promise<Post[]>;
     get(slug: string): Promise<Post | null>;
@@ -331,6 +1715,18 @@ interface PostsProvider {
     create(data: CreatePostInput): Promise<Post>;
     update(postId: string, data: Partial<Post>): Promise<Post>;
     remove(postId: string): Promise<void>;
+    listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
+    /**
+     * Return lightweight summaries for all posts (no body / metadata).
+     * Implementations MUST page through all nextToken values to return the
+     * complete list — the admin list view depends on this for accurate search
+     * and sort.
+     *
+     * Optional: providers that do not implement this fall back to a best-effort
+     * single-page result via `list()` (see `listPostSummaries` fallback path).
+     * The admin provider always implements this.
+     */
+    listSummaries?(opts?: SummaryListOptions): Promise<PostSummary[]>;
 }
 declare function setPostsProvider(p: PostsProvider): void;
 declare function hasPostsProvider(): boolean;
@@ -340,6 +1736,30 @@ declare function getPostById(postId: string): Promise<Post | null>;
 declare function createPost(data: CreatePostInput): Promise<Post>;
 declare function updatePost(postId: string, data: Partial<Post>): Promise<Post>;
 declare function deletePost(postId: string): Promise<void>;
+/**
+ * List a post's revision history, newest-first. Backed by the
+ * `PostHistory` `byPost` GSI. Requires a configured provider (the dummy
+ * fallback has no history) — returns an empty connection otherwise so
+ * callers (e.g. the admin history panel) degrade gracefully.
+ */
+declare function listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
+/**
+ * Return lightweight summaries for all posts (no body / metadata).
+ *
+ * Delegates to `provider.listSummaries()` when available — the admin
+ * provider implements this with a full nextToken loop and selectionSet
+ * projection, ensuring all posts are returned without fetching large body
+ * fields.
+ *
+ * **Fallback**: if the configured provider does not implement `listSummaries`,
+ * falls back to a single page from `provider.list({ status })`. This is
+ * best-effort only — it returns at most one page of results (no pagination).
+ * Providers that need complete summary lists MUST implement `listSummaries`.
+ * A `console.warn` is emitted once to make this visible.
+ *
+ * If no provider is configured, maps DUMMY_POSTS to summaries.
+ */
+declare function listPostSummaries(opts?: SummaryListOptions): Promise<PostSummary[]>;
 
 interface KvItem<T = unknown> {
     pk: string;
@@ -361,8 +1781,8 @@ declare function hasKvStore(): boolean;
 /**
  * Access the injected `KvStore` directly. Use the site-setting helpers
  * (`getSiteSetting` etc.) when storing per-site configuration; reach
- * for this lower-level handle only when you need a different PK
- * namespace (e.g. `mcp-tokens`).
+ * for this lower-level handle when you need a different PK namespace
+ * (plugin caches, ad-hoc shared state, etc.).
  */
 declare function getKvStore(): KvStore;
 declare const SITE_CONFIG_PK = "siteconfig";
@@ -418,9 +1838,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 legacy 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
@@ -431,17 +1850,73 @@ 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;
 
 /**
  * Build the public S3 URL for an object key, in the regional virtual-host
- * style: `https://{bucket}.s3.{region}.amazonaws.com/{key}`. The legacy
+ * style: `https://{bucket}.s3.{region}.amazonaws.com/{key}`. The
  * non-regional form (`s3.amazonaws.com`) issues redirects and is avoided.
  */
 declare function formatPublicAssetUrl(bucket: string, region: string, key: string): string;
 
+/**
+ * Validate the user-supplied key for ctx.writePublicAsset.
+ *
+ * The trusted Lambda still has a processor-wide S3 grant, so path safety is
+ * enforced at the runtime context boundary before the key is joined under the
+ * plugin namespace.
+ */
+declare function validatePublicAssetKey(key: string): string | null;
+
+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, mode?: 'strict' | 'lenient'): 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
@@ -457,6 +1932,17 @@ declare function formatPublicAssetUrl(bucket: string, region: string, key: strin
  */
 declare function extractFirstImageUrl(post: Post): string | null;
 
+type PostListStatusFilter = 'all' | 'draft' | 'published';
+type PostListSort = 'updated-desc' | 'updated-asc' | 'published-desc' | 'published-asc' | 'title-asc' | 'title-desc';
+interface PostListFilterOptions {
+    query?: string;
+    status?: PostListStatusFilter;
+    tag?: string;
+    sort?: PostListSort;
+}
+declare function filterSortPostSummaries<T extends PostSummary>(rows: readonly T[], options?: PostListFilterOptions): T[];
+declare function collectTags(rows: readonly PostSummary[]): Map<string, number>;
+
 /**
  * Pure helpers for `format: 'static'` post bundles. Kept platform-free
  * (no `File`, no Amplify Storage, no AWS SDK) so both the browser admin
@@ -545,215 +2031,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 & {
-        siteId: string;
-    }>;
-}
-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 under
-     * `app/site/[siteId]/`. 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 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 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 ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, 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 PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostListFilterOptions, type PostListSort, type PostListStatusFilter, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostSummary, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, type SummaryListOptions, 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 TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, collectTags, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, filterSortPostSummaries, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };