@janmarkuslanger/astro-strapi-platform 0.1.0 → 0.1.1

package/dist/core/blocks.d.ts

@@ -0,0 +1,34 @@
+import type { BaseBlock } from "./types.js";
+export type JsonLd = Record<string, unknown>;
+/**
+ * The block contract: everything the platform needs to know about one block
+ * type, in one object. Platform code (adapter, renderer, llms.txt, JSON-LD)
+ * iterates over registered definitions and never names a block type itself.
+ *
+ * `C` is the CMS side, owned by the adapter package (e.g. a Strapi mapping);
+ * core never looks inside it. Every field except `jsonLd` is required, so a
+ * half-registered block cannot compile.
+ */
+export interface BlockDefinition<B extends BaseBlock, C = unknown> {
+    /** CMS side: read only by the adapter. */
+    cms: C;
+    /** Renders the block. Receives it as the `block` prop. */
+    component: (props: {
+        block: B;
+    }) => unknown;
+    /** Facts for llms.txt. `[]` is a valid answer — but it must be a decision. */
+    llms: (block: B) => string[];
+    /** JSON-LD nodes derived from the block, e.g. FAQPage for an FAQ block. */
+    jsonLd?: (block: B) => JsonLd[];
+}
+/**
+ * One definition per member of the site's block union. Typing a registry with
+ * this makes a missing block a compile error.
+ */
+export type BlockRegistry<B extends BaseBlock> = {
+    [T in B["type"]]: BlockDefinition<Extract<B, {
+        type: T;
+    }>>;
+};
+/** Definition for a block, or undefined for a type the registry does not know. */
+export declare function definitionFor<B extends BaseBlock>(registry: BlockRegistry<B>, block: B): BlockDefinition<B> | undefined;

package/dist/core/blocks.js

@@ -0,0 +1,7 @@
+/** Definition for a block, or undefined for a type the registry does not know. */
+export function definitionFor(registry, block) {
+    // Sound: each key holds the definition for exactly that type. TypeScript
+    // cannot reduce Extract<B, { type: B["type"] }> back to B, so say it once.
+    // `undefined` covers a block whose type the registry does not know.
+    return registry[block.type];
+}

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./repository.js";
+export * from "./blocks.js";
+export * from "./paths.js";
+export { buildLlmsTxt } from "./llms.js";
+export { organizationSchema, pageSchemas } from "./seo.js";

package/dist/core/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./repository.js";
+export * from "./blocks.js";
+export * from "./paths.js";
+export { buildLlmsTxt } from "./llms.js";
+export { organizationSchema, pageSchemas } from "./seo.js";

package/dist/core/llms.d.ts

@@ -0,0 +1,3 @@
+import { type BlockRegistry } from "./blocks.js";
+import type { BaseBlock, Page, SiteGlobal } from "./types.js";
+export declare function buildLlmsTxt<B extends BaseBlock>(global: SiteGlobal, pages: Page<B>[], siteUrl: string, blocks: BlockRegistry<B>): string;

package/dist/core/llms.js

@@ -0,0 +1,42 @@
+import { definitionFor } from "./blocks.js";
+import { pageHref, slugOfHref } from "./paths.js";
+/**
+ * Builds `llms.txt` (llmstxt.org) — a compact site summary for generative
+ * search engines. Generated from the domain model at build time, never
+ * hand-maintained, so it cannot drift away from the site.
+ *
+ * What each block contributes is its definition's `llms` — a required field,
+ * so a new block type fails the build until someone decides. Often the answer
+ * is `[]`, but it has to be a decision rather than an oversight; that is what
+ * keeps this file accurate as a project grows.
+ */
+function truncate(value, max = 300) {
+    return value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;
+}
+export function buildLlmsTxt(global, pages, siteUrl, blocks) {
+    const lines = [];
+    lines.push(`# ${global.siteName}`);
+    if (global.claim)
+        lines.push(`\n> ${global.claim}`);
+    lines.push(`\nContact: ${global.email}`);
+    // Navigation order is the site's own idea of importance — reuse it instead
+    // of inventing a ranking.
+    const rank = (slug) => {
+        const i = global.navigation.findIndex((n) => slugOfHref(n.href) === slug);
+        return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+    };
+    const ordered = [...pages].sort((a, b) => rank(a.slug) - rank(b.slug));
+    lines.push("\n## Pages\n");
+    for (const page of ordered) {
+        lines.push(`### ${page.title}`);
+        lines.push(`${siteUrl}${pageHref(page.slug)}`);
+        if (page.seo.description)
+            lines.push(page.seo.description);
+        const facts = page.blocks.flatMap((block) => definitionFor(blocks, block)?.llms(block) ?? []);
+        for (const fact of facts.filter(Boolean)) {
+            lines.push(`- ${truncate(fact)}`);
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n").trim()}\n`;
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The page with this slug renders at "/", so editors create the home page
+ * like any other page — no special content type, no special case.
+ */
+export declare const HOME_SLUG = "home";
+/** Site-relative URL of a page: "/" for the home page, "/<slug>/" otherwise. */
+export declare function pageHref(slug: string): string;
+/** Inverse of {@link pageHref} for internal links, e.g. navigation entries. */
+export declare function slugOfHref(href: string): string;

package/dist/core/paths.js

@@ -0,0 +1,13 @@
+/**
+ * The page with this slug renders at "/", so editors create the home page
+ * like any other page — no special content type, no special case.
+ */
+export const HOME_SLUG = "home";
+/** Site-relative URL of a page: "/" for the home page, "/<slug>/" otherwise. */
+export function pageHref(slug) {
+    return slug === HOME_SLUG ? "/" : `/${slug}/`;
+}
+/** Inverse of {@link pageHref} for internal links, e.g. navigation entries. */
+export function slugOfHref(href) {
+    return href.replace(/^\/|\/$/g, "") || HOME_SLUG;
+}

package/dist/core/repository.d.ts

@@ -0,0 +1,18 @@
+import type { BaseBlock, Page, SiteGlobal } from "./types.js";
+/**
+ * The contract every CMS adapter must fulfill. Pages and components only ever
+ * talk to an object shaped like this — they never learn whether the data came
+ * from Strapi, a JSON file, or anything else.
+ *
+ * `P` and `G` are the site's own page and global fields (see `Page`). A site
+ * that reads its own content types declares a repository extending this one.
+ *
+ * Keep query objects (rather than long parameter lists) for anything a
+ * listing block can configure — that is what lets a block carry a *selection*
+ * while the component fetches the data.
+ */
+export interface CmsRepository<B extends BaseBlock = BaseBlock, P extends object = {}, G extends object = {}> {
+    getGlobal(): Promise<SiteGlobal<G>>;
+    listPages(): Promise<Page<B, P>[]>;
+    getPage(slug: string): Promise<Page<B, P> | null>;
+}

package/dist/core/repository.js

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

package/dist/core/seo.d.ts

@@ -0,0 +1,13 @@
+import { type BlockRegistry, type JsonLd } from "./blocks.js";
+import type { BaseBlock, Page, SiteGlobal } from "./types.js";
+/**
+ * Structured data (JSON-LD).
+ *
+ * The pattern worth keeping: DERIVE schemas from the content blocks rather
+ * than maintaining them by hand. A block definition's optional `jsonLd` turns
+ * its block into nodes, so an editor who adds an FAQ block to a page gets
+ * `FAQPage` markup with nobody touching code — and a new page is correct by
+ * default instead of forgotten.
+ */
+export declare function organizationSchema(global: SiteGlobal, siteUrl: string): JsonLd;
+export declare function pageSchemas<B extends BaseBlock>(page: Page<B>, global: SiteGlobal, siteUrl: string, blocks: BlockRegistry<B>): JsonLd[];

package/dist/core/seo.js

@@ -0,0 +1,34 @@
+import { definitionFor } from "./blocks.js";
+import { HOME_SLUG } from "./paths.js";
+/**
+ * Structured data (JSON-LD).
+ *
+ * The pattern worth keeping: DERIVE schemas from the content blocks rather
+ * than maintaining them by hand. A block definition's optional `jsonLd` turns
+ * its block into nodes, so an editor who adds an FAQ block to a page gets
+ * `FAQPage` markup with nobody touching code — and a new page is correct by
+ * default instead of forgotten.
+ */
+export function organizationSchema(global, siteUrl) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        name: global.siteName,
+        url: siteUrl,
+        email: global.email,
+        ...(global.claim ? { description: global.claim } : {}),
+    };
+}
+export function pageSchemas(page, global, siteUrl, blocks) {
+    const schemas = [];
+    // Only the homepage carries the organization node — repeating it on every
+    // page adds noise without adding information.
+    if (page.slug === HOME_SLUG)
+        schemas.push(organizationSchema(global, siteUrl));
+    // Derived from block type, never from page slug: a slug-based rule breaks
+    // the moment an editor renames a page or reuses the block somewhere else.
+    for (const block of page.blocks) {
+        schemas.push(...(definitionFor(blocks, block)?.jsonLd?.(block) ?? []));
+    }
+    return schemas;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Domain model shared by every site. This is the ONLY shape pages and
+ * components may depend on; whatever CMS sits behind it is translated into
+ * these types by its adapter.
+ *
+ * Blocks are not defined here: the content model is where sites differ. A
+ * site declares its own `Block` union and passes it in as `B`.
+ */
+export interface Seo {
+    title: string;
+    description: string;
+}
+export interface ImageAsset {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+export interface Link {
+    label: string;
+    href: string;
+}
+/** Every block has a `type` discriminator; the rest is the block's own. */
+export interface BaseBlock {
+    type: string;
+}
+/** The fields every site's pages have; the platform owns them. */
+export interface PageFields<B extends BaseBlock = BaseBlock> {
+    slug: string;
+    title: string;
+    seo: Seo;
+    blocks: B[];
+}
+/**
+ * A page as a site sees it: the platform fields plus `X`, the fields the site
+ * added to its page schema (`schema-extensions/page.json`). `X` cannot
+ * replace a platform field — the adapter writes those last.
+ */
+export type Page<B extends BaseBlock = BaseBlock, X extends object = {}> = PageFields<B> & X;
+/** The fields every site's global settings have; the platform owns them. */
+export interface SiteGlobalFields {
+    siteName: string;
+    claim?: string;
+    email: string;
+    navigation: Link[];
+    footerLinks: Link[];
+}
+/** Global settings plus the site's own fields, as for {@link Page}. */
+export type SiteGlobal<X extends object = {}> = SiteGlobalFields & X;

package/dist/core/types.js

@@ -0,0 +1,9 @@
+/**
+ * Domain model shared by every site. This is the ONLY shape pages and
+ * components may depend on; whatever CMS sits behind it is translated into
+ * these types by its adapter.
+ *
+ * Blocks are not defined here: the content model is where sites differ. A
+ * site declares its own `Block` union and passes it in as `B`.
+ */
+export {};

package/dist/strapi/adapter.d.ts

@@ -0,0 +1,91 @@
+import type { BaseBlock, CmsRepository, Page, SiteGlobal } from "../core/index.js";
+import { type MapContext, type StrapiExtension, type StrapiBlockRegistry } from "./mapper.js";
+interface BaseOptions<B extends BaseBlock> {
+    /**
+     * Where THIS process fetches from at build time. May be 127.0.0.1 when
+     * building on the CMS host — never localhost (IPv6, see CLAUDE.md §4).
+     */
+    url: string;
+    /** Optional read-only API token. */
+    token?: string;
+    /**
+     * What ends up in the HTML — image sources, form endpoints — loaded later by
+     * the VISITOR's browser, where 127.0.0.1 means their own machine. Defaults
+     * to `url`, which is only right when that URL is public.
+     */
+    mediaUrl?: string;
+    /** The site's block registry; the adapter reads each definition's `cms`. */
+    blocks: StrapiBlockRegistry<B>;
+}
+/**
+ * Required as soon as the site declares fields `X`, optional ones included —
+ * a page type promising a field nobody maps would compile and then render
+ * `undefined`.
+ */
+type ExtensionOption<K extends string, X extends object> = [keyof X] extends [never] ? {
+    [key in K]?: StrapiExtension<X>;
+} : {
+    [key in K]: StrapiExtension<X>;
+};
+export type StrapiCmsAdapterOptions<B extends BaseBlock, P extends object = {}, G extends object = {}> = BaseOptions<B> & ExtensionOption<"page", P> & ExtensionOption<"global", G>;
+export declare class StrapiCmsAdapter<B extends BaseBlock = BaseBlock, P extends object = {}, G extends object = {}> implements CmsRepository<B, P, G> {
+    private readonly url;
+    private readonly token;
+    private readonly mediaUrl;
+    private readonly pageExtension;
+    private readonly globalExtension;
+    private readonly globalPopulate;
+    /** Strapi side of every registered block, keyed by domain type. */
+    private readonly blocks;
+    /** Cache so a page with five references costs one extra request, not five. */
+    private sharedBlocks;
+    /**
+     * Populate query so Strapi ships every component and media file of the
+     * dynamic zone. Derived from the registered blocks; a block whose nested
+     * fields arrive empty needs its own `populate` (see StrapiBlockMapping).
+     */
+    private readonly populate;
+    /**
+     * Pages additionally need their `seo` component. Strapi 5 populates no
+     * component unless asked, so without this every page silently loses its
+     * title and meta description.
+     */
+    private readonly pagePopulate;
+    /**
+     * `image` and `markdown` bound to the public media URL, for a site mapping
+     * its own content types (see `get`).
+     */
+    readonly context: MapContext;
+    constructor(options: StrapiCmsAdapterOptions<B, P, G>);
+    /**
+     * Retries connection failures and gateway statuses with a short backoff.
+     *
+     * A build often starts right after the CMS restarts. A connect timeout or a
+     * 502 in those first seconds is a blip, not an outage, and should not fail a
+     * whole site build. Real errors (404, 401) fail on the first try — no wasted
+     * backoff on a genuine mistake.
+     */
+    private fetchWithRetry;
+    /**
+     * GET against the Strapi REST API, with the token and the retry above. For
+     * a site's own content types: the site maps the response itself, using
+     * `context` for media and Markdown.
+     *
+     *   const json = await strapi.get("/api/posts?populate[cover]=true");
+     *   json.data.map((e) => ({ title: e.title, cover: strapi.context.image(e.cover) }));
+     */
+    get(path: string): Promise<any>;
+    /**
+     * Resolves `blocks.reference` into the blocks of the shared block it points
+     * at. Done here so the domain model never sees a reference.
+     *
+     * Shared blocks may not contain references themselves, so there is nothing
+     * to recurse into and cycles are impossible by construction — no runtime
+     * cycle detection needed.
+     */
+    private blockResolver;
+    getGlobal(): Promise<SiteGlobal<G>>;
+    listPages(): Promise<Page<B, P>[]>;
+    getPage(slug: string): Promise<Page<B, P> | null>;
+}
+export {};

package/dist/strapi/adapter.js

@@ -0,0 +1,129 @@
+import { blockPopulate, mapBlocks, mapContext, mapGlobal, mapPage, } from "./mapper.js";
+export class StrapiCmsAdapter {
+    url;
+    token;
+    mediaUrl;
+    pageExtension;
+    globalExtension;
+    globalPopulate;
+    /** Strapi side of every registered block, keyed by domain type. */
+    blocks;
+    /** Cache so a page with five references costs one extra request, not five. */
+    sharedBlocks = null;
+    /**
+     * Populate query so Strapi ships every component and media file of the
+     * dynamic zone. Derived from the registered blocks; a block whose nested
+     * fields arrive empty needs its own `populate` (see StrapiBlockMapping).
+     */
+    populate;
+    /**
+     * Pages additionally need their `seo` component. Strapi 5 populates no
+     * component unless asked, so without this every page silently loses its
+     * title and meta description.
+     */
+    pagePopulate;
+    /**
+     * `image` and `markdown` bound to the public media URL, for a site mapping
+     * its own content types (see `get`).
+     */
+    context;
+    constructor(options) {
+        this.url = options.url;
+        this.token = options.token;
+        this.mediaUrl = options.mediaUrl || options.url;
+        this.context = mapContext(this.mediaUrl);
+        const extensions = options;
+        this.pageExtension = extensions.page;
+        this.globalExtension = extensions.global;
+        // Every value of a StrapiBlockRegistry has a Strapi `cms`; TypeScript
+        // cannot see through a mapped type over a generic union, so say it once.
+        const definitions = Object.entries(options.blocks);
+        this.blocks = Object.fromEntries(definitions.map(([type, definition]) => [type, definition.cms]));
+        this.populate = blockPopulate(this.blocks);
+        const extra = (extension) => extension?.populate ? `&${extension.populate}` : "";
+        this.pagePopulate = `populate[seo]=true&${this.populate}${extra(this.pageExtension)}`;
+        this.globalPopulate = `populate[navigation]=true&populate[footerLinks]=true${extra(this.globalExtension)}`;
+    }
+    /**
+     * Retries connection failures and gateway statuses with a short backoff.
+     *
+     * A build often starts right after the CMS restarts. A connect timeout or a
+     * 502 in those first seconds is a blip, not an outage, and should not fail a
+     * whole site build. Real errors (404, 401) fail on the first try — no wasted
+     * backoff on a genuine mistake.
+     */
+    async fetchWithRetry(url, init, attempt = 1) {
+        const maxAttempts = 4;
+        const retryable = (s) => s === 502 || s === 503 || s === 504;
+        let res;
+        try {
+            res = await fetch(url, init);
+        }
+        catch (error) {
+            if (attempt >= maxAttempts)
+                throw error;
+            await new Promise((r) => setTimeout(r, attempt * 2000));
+            return this.fetchWithRetry(url, init, attempt + 1);
+        }
+        if (!res.ok && retryable(res.status) && attempt < maxAttempts) {
+            await new Promise((r) => setTimeout(r, attempt * 2000));
+            return this.fetchWithRetry(url, init, attempt + 1);
+        }
+        return res;
+    }
+    /**
+     * GET against the Strapi REST API, with the token and the retry above. For
+     * a site's own content types: the site maps the response itself, using
+     * `context` for media and Markdown.
+     *
+     *   const json = await strapi.get("/api/posts?populate[cover]=true");
+     *   json.data.map((e) => ({ title: e.title, cover: strapi.context.image(e.cover) }));
+     */
+    async get(path) {
+        const headers = {};
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        const res = await this.fetchWithRetry(`${this.url}${path}`, { headers });
+        if (!res.ok) {
+            throw new Error(`Strapi request failed: ${res.status} ${res.statusText} (${path})`);
+        }
+        return res.json();
+    }
+    /**
+     * Resolves `blocks.reference` into the blocks of the shared block it points
+     * at. Done here so the domain model never sees a reference.
+     *
+     * Shared blocks may not contain references themselves, so there is nothing
+     * to recurse into and cycles are impossible by construction — no runtime
+     * cycle detection needed.
+     */
+    async blockResolver() {
+        if (!this.sharedBlocks) {
+            const json = await this.get(`/api/shared-blocks?${this.populate}`);
+            this.sharedBlocks = new Map((json.data ?? []).map((entry) => [
+                String(entry.documentId ?? entry.id),
+                mapBlocks(entry.blocks ?? [], this.mediaUrl, this.blocks),
+            ]));
+        }
+        const cache = this.sharedBlocks;
+        return (id) => cache.get(id) ?? [];
+    }
+    async getGlobal() {
+        const json = await this.get(`/api/global?${this.globalPopulate}`);
+        return mapGlobal(json.data ?? {}, this.mediaUrl, this.globalExtension);
+    }
+    // Mapped blocks are B by construction: only registered types survive the
+    // mapper. The cast states that; it cannot be checked across the CMS boundary.
+    async listPages() {
+        const json = await this.get(`/api/pages?${this.pagePopulate}`);
+        const resolve = await this.blockResolver();
+        return (json.data ?? []).map((e) => mapPage(e, this.mediaUrl, this.blocks, resolve, this.pageExtension));
+    }
+    async getPage(slug) {
+        const json = await this.get(`/api/pages?filters[slug][$eq]=${encodeURIComponent(slug)}&${this.pagePopulate}`);
+        const entry = (json.data ?? [])[0];
+        if (!entry)
+            return null;
+        return mapPage(entry, this.mediaUrl, this.blocks, await this.blockResolver(), this.pageExtension);
+    }
+}

package/dist/strapi/index.d.ts

@@ -0,0 +1,11 @@
+import type { BaseBlock, BlockDefinition } from "../core/index.js";
+import type { StrapiBlockMapping } from "./mapper.js";
+export { StrapiCmsAdapter, type StrapiCmsAdapterOptions } from "./adapter.js";
+export type { MapContext, StrapiBlockMapping, StrapiBlockRegistry, StrapiExtension, } from "./mapper.js";
+/**
+ * Declares a block whose CMS side is Strapi. Identity at runtime; exists so a
+ * block module gets its types checked where it is written:
+ *
+ *   export default defineBlock<HeroBlock>({ cms: { component, map }, component, llms });
+ */
+export declare function defineBlock<B extends BaseBlock>(definition: BlockDefinition<B, StrapiBlockMapping<B>>): BlockDefinition<B, StrapiBlockMapping<B>>;

package/dist/strapi/index.js

@@ -0,0 +1,10 @@
+export { StrapiCmsAdapter } from "./adapter.js";
+/**
+ * Declares a block whose CMS side is Strapi. Identity at runtime; exists so a
+ * block module gets its types checked where it is written:
+ *
+ *   export default defineBlock<HeroBlock>({ cms: { component, map }, component, llms });
+ */
+export function defineBlock(definition) {
+    return definition;
+}

package/dist/strapi/mapper.d.ts

@@ -0,0 +1,74 @@
+import type { BaseBlock, BlockDefinition, ImageAsset, Page, SiteGlobal } from "../core/index.js";
+/** Resolves a shared-block id into its blocks. Supplied by the adapter. */
+export type BlockResolver = (id: string) => BaseBlock[];
+/**
+ * Component id of the reference block. Adapter-internal: references are
+ * resolved here and never reach the domain model.
+ */
+export declare const REFERENCE_COMPONENT = "blocks.reference";
+/** Helpers a block's `map` gets, so no block re-implements URL or Markdown handling. */
+export interface MapContext {
+    image(raw: any): ImageAsset | undefined;
+    markdown(value: unknown): string;
+}
+/**
+ * Site fields on a platform type (`page`, `global`), added in Strapi through
+ * `schema-extensions/`. The adapter fetches them with `populate` and merges
+ * `map`'s result under the platform fields.
+ */
+export interface StrapiExtension<X extends object> {
+    /**
+     * Extra populate parameters, e.g. `populate[hero]=true`. Plain fields
+     * (strings, numbers, booleans) need none; media, components and relations
+     * arrive empty without it.
+     */
+    populate?: string;
+    /** Raw Strapi entry → the site's fields. */
+    map(raw: any, ctx: MapContext): X;
+}
+/** Strapi side of a block definition — the `cms` field of `defineBlock`. */
+export interface StrapiBlockMapping<B extends BaseBlock> {
+    /** Strapi component id, e.g. "blocks.hero". */
+    component: string;
+    /**
+     * Populate fragment after `populate[blocks][on][<component>]`. Defaults to
+     * `[populate]=*` (one level). Blocks with deeper nesting (items with images,
+     * links in a list) must spell it out, or those fields arrive empty.
+     */
+    populate?: string;
+    /** Strapi component → domain block, without `type` (added by the mapper). */
+    map(raw: any, ctx: MapContext): Omit<B, "type">;
+}
+/** A block registry whose CMS side is Strapi: one definition per member of `B`. */
+export type StrapiBlockRegistry<B extends BaseBlock> = {
+    [T in B["type"]]: BlockDefinition<Extract<B, {
+        type: T;
+    }>, StrapiBlockMapping<Extract<B, {
+        type: T;
+    }>>>;
+};
+/** Strapi mappings keyed by domain block type. */
+export type StrapiBlockMappings = Record<string, StrapiBlockMapping<BaseBlock>>;
+/** Populate query for a dynamic zone holding these blocks plus references. */
+export declare function blockPopulate(mappings: StrapiBlockMappings): string;
+/**
+ * Media URLs arrive relative from Strapi ("/uploads/x.jpg"). They must become
+ * absolute against the PUBLIC base, not the build-time base — the visitor's
+ * browser loads them, not the build. See CLAUDE.md §4.
+ *
+ * Offered to every block's `map` as `ctx.image`, so no block can get this
+ * wrong — it is the classic production-only bug.
+ */
+export declare function mapImage(raw: any, mediaUrl: string): ImageAsset | undefined;
+/** The helpers handed to every `map`, bound to the public media URL. */
+export declare function mapContext(mediaUrl: string): MapContext;
+/**
+ * Turns Strapi's dynamic zone into domain blocks, using the registered
+ * mappings.
+ *
+ * Unknown component ids are SKIPPED, not thrown on: a block added in the CMS
+ * before the frontend knows it must never take the site down.
+ */
+export declare function mapBlocks(raw: any[], mediaUrl: string, mappings: StrapiBlockMappings, resolve?: BlockResolver): BaseBlock[];
+export declare function mapPage<X extends object = {}>(entry: any, mediaUrl: string, mappings: StrapiBlockMappings, resolve?: BlockResolver, extension?: StrapiExtension<X>): Page<BaseBlock, X>;
+export declare function mapGlobal<X extends object = {}>(entry: any, mediaUrl: string, extension?: StrapiExtension<X>): SiteGlobal<X>;