@omniharmonic/openspace-renderer 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,798 @@
+import { B as BehaviorName } from './base-css-CCRQ8Nzw.js';
+export { a as BASE_CSS, b as BEHAVIORS, c as BEHAVIOR_BUDGETS, d as BEHAVIOR_LOADER, e as behaviorsInHtml, i as isBehaviorName } from './base-css-CCRQ8Nzw.js';
+import * as react from 'react';
+import { ReactNode, AnchorHTMLAttributes } from 'react';
+import { AnyBlockDefinition, BlockDefinition, FieldsShape, Block, Section, RichTextDoc, SiteDocument, Page, Responsive, Align, BlockStyle, Announcement, Site, ColorTheme, Popup as Popup$1, CollectionItem, CollectionConfig, ImageValue, ReferenceValue, HeaderVariant, Header as Header$1, NavItem, Styles, FocalPoint, AspectRatio, ImageTreatment, StackLayout, GridLayout, GridRect, SectionStyle, Link as Link$1, SocialProfile, TypePreset, SectionBackground } from '@omniharmonic/openspace-schema';
+export { fallbackMobileRects } from '@omniharmonic/openspace-schema';
+import { CompiledStyles } from '@omniharmonic/openspace-theme';
+
+/**
+ * The image resolution contract (arch §4.3). site-kit walks a page, resolves every image through
+ * Astro's `getImage()` and passes the result in; `<Img>` reads it. Keys are the `src` exactly as
+ * stored in content (`media/2026/10/hero.jpg` or an https URL).
+ */
+interface ResolvedImageSource {
+    /** MIME type, e.g. `image/avif`, `image/webp`. */
+    type: string;
+    srcset: string;
+}
+interface ResolvedImage {
+    /** Fallback URL (JPEG/PNG) for `<img src>`. */
+    src: string;
+    /** Fallback-format srcset for `<img srcset>`. */
+    srcset?: string;
+    /** Modern formats, best first, rendered as `<source>`s. */
+    sources?: ResolvedImageSource[];
+    /** Intrinsic dimensions (always emitted: no layout shift). */
+    width: number;
+    height: number;
+    /** Tiny blurred placeholder data URI (< 300 bytes). */
+    placeholder?: string;
+}
+type ImageMap = Readonly<Record<string, ResolvedImage>>;
+/** Every image `src` referenced by a JSON value (pages, site, blocks). */
+declare function collectImageSrcs(value: unknown, out?: Set<string>): Set<string>;
+
+/**
+ * A block definition whose `render` returns React nodes. Schema keeps `render` generic
+ * (`(props) => unknown`) so it has no React dependency; the renderer narrows it here.
+ */
+type RendererBlockDefinition = BlockDefinition<any, any, ReactNode>;
+/** The minimal registry surface the renderer needs (schema's `BlockRegistry` satisfies it). */
+interface RendererBlockRegistry {
+    get(type: string): AnyBlockDefinition | undefined;
+}
+/**
+ * Register block definitions with the renderer. Re-registering a type replaces it (hot reload,
+ * custom blocks overriding library blocks).
+ */
+declare function registerBlocks(defs: readonly (AnyBlockDefinition | BlockDefinition<FieldsShape, string, ReactNode>)[]): void;
+/** Look up a registered block definition. */
+declare function getBlock(type: string): RendererBlockDefinition | undefined;
+/** All registered definitions. */
+declare function listBlocks(): RendererBlockDefinition[];
+/** Remove one type, or every registration when called without arguments (tests). */
+declare function unregisterBlocks(...types: string[]): void;
+/** The module-level registry as a {@link RendererBlockRegistry}. */
+declare const globalRegistry: RendererBlockRegistry;
+
+/**
+ * Render modes.
+ * - `production`: the published site (site-kit build). Broken references render nothing.
+ * - `preview`: Hub dev preview / share links. Like production, plus visible notices for broken
+ *   blocks and links, and always `noindex`.
+ * - `editor`: Studio canvas. Like preview, plus no entrance animations and editor hooks.
+ */
+type RenderMode = "production" | "preview" | "editor";
+interface RenderContextValue {
+    /** The whole site; optional so primitives (`<Img>`, `<Link>`) can render standalone. */
+    doc: SiteDocument | undefined;
+    /** The page being rendered, if any (used for same-page anchors). */
+    page: Page | undefined;
+    mode: RenderMode;
+    /** Site base path without a trailing slash: `""` or `/maya-yoga`. */
+    basePath: string;
+    /** Hub origin used by forms, newsletter, cart and analytics. */
+    hubUrl: string | undefined;
+}
+declare const RenderContext: react.Context<RenderContextValue>;
+declare function useRenderContext(): RenderContextValue;
+/** Resolved image map (see {@link ImageMap}); `<Img>` reads it. */
+declare const ImageResolverContext: react.Context<Readonly<Record<string, ResolvedImage>>>;
+declare function useImageMap(): ImageMap;
+/** Optional block registry override (defaults to the module-level registry). */
+declare const BlockRegistryContext: react.Context<RendererBlockRegistry | undefined>;
+/**
+ * Hook point for Studio. The renderer always emits `data-os-id` on sections and blocks; in the
+ * canvas, Studio can additionally wrap each rendered section/block (selection outlines,
+ * drag handles) without the renderer knowing anything about the editor.
+ */
+interface EditorHooks {
+    wrapSection?: (args: {
+        section: Section;
+        children: ReactNode;
+    }) => ReactNode;
+    wrapBlock?: (args: {
+        block: Block;
+        section: Section | undefined;
+        children: ReactNode;
+    }) => ReactNode;
+    /** Rendered in place of unknown/invalid blocks (defaults to a small notice). */
+    renderMissingBlock?: (args: {
+        block: Block;
+        reason: string;
+    }) => ReactNode;
+    /**
+     * Called by `<RichText>` for a rich-text value that is one of the current block's fields, so
+     * Studio can swap in an inline editor. `children` is what `<RichText>` would have rendered
+     * (null for an empty document); return it unchanged to keep the normal output.
+     */
+    renderRichText?: (args: RichTextHookArgs) => ReactNode;
+}
+interface RichTextHookArgs {
+    block: Block;
+    /** Dot path of the field inside `block.fields`, e.g. `content` or `items.2.body`. */
+    fieldPath: string;
+    doc: RichTextDoc | null | undefined;
+    /** Classes `<RichText>` puts on its root next to `os-rich`. */
+    className: string | undefined;
+    /** Root element `<RichText>` renders. */
+    as: "div" | "section" | "article";
+    children: ReactNode;
+}
+declare const EditorContext: react.Context<EditorHooks | undefined>;
+declare function useEditor(): EditorHooks | undefined;
+/** The block being rendered and its validated fields (lets `<RichText>` find its field path). */
+declare const BlockFieldsContext: react.Context<{
+    block: Block;
+    fields: Record<string, unknown>;
+} | undefined>;
+/**
+ * Where `value` sits inside `fields`, by identity (`items.1.body`). Render functions pass field
+ * values straight through, so the object `<RichText>` receives is the one in `fields`.
+ */
+declare function fieldPathOf(fields: Record<string, unknown>, value: unknown, depth?: number): string | undefined;
+/** The section currently being rendered (blocks use it for context, e.g. color theme). */
+declare const SectionContext: react.Context<{
+    id: `sec_${string}`;
+    layout: {
+        mode: "stack";
+        columns: {
+            d: number[];
+            t?: number[] | undefined;
+            m?: number[] | undefined;
+        };
+        order?: {
+            t?: number[] | undefined;
+            m?: number[] | undefined;
+        } | undefined;
+        align?: "start" | "center" | "end" | "stretch" | undefined;
+        gap?: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
+        width?: "full" | "narrow" | "content" | "wide" | undefined;
+    } | {
+        mode: "grid";
+        rows: {
+            d: number;
+            t?: number | undefined;
+            m?: number | undefined;
+        };
+        items: Record<`blk_${string}`, {
+            d: {
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                z?: number | undefined;
+                bleed?: "left" | "right" | "both" | undefined;
+                pin?: "top" | "bottom" | undefined;
+            };
+            t?: {
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                z?: number | undefined;
+                bleed?: "left" | "right" | "both" | undefined;
+                pin?: "top" | "bottom" | undefined;
+            } | undefined;
+            m?: {
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                z?: number | undefined;
+                bleed?: "left" | "right" | "both" | undefined;
+                pin?: "top" | "bottom" | undefined;
+            } | undefined;
+        }>;
+        width?: "full" | "narrow" | "content" | "wide" | undefined;
+    };
+    style: {
+        colorTheme?: "light" | "light-accent" | "dark" | "dark-accent" | "brand" | undefined;
+        padding?: {
+            d: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+            t?: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
+            m?: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
+        } | undefined;
+        minHeight?: {
+            d: string;
+            t?: string | undefined;
+            m?: string | undefined;
+        } | undefined;
+        background?: {
+            type: "none";
+        } | {
+            type: "color";
+            color: string;
+        } | {
+            type: "image";
+            src: string;
+            focal?: [number, number] | undefined;
+            overlay?: {
+                color: string;
+                opacity: number;
+            } | undefined;
+            parallax?: boolean | undefined;
+        } | {
+            type: "gradient";
+            from: string;
+            to: string;
+            via?: string | undefined;
+            angle?: number | undefined;
+        } | {
+            type: "video";
+            src: string;
+            poster?: string | undefined;
+            focal?: [number, number] | undefined;
+            overlay?: {
+                color: string;
+                opacity: number;
+            } | undefined;
+        } | undefined;
+        animation?: {
+            entrance: "none" | "fade" | "rise" | "slide" | "zoom" | "clip";
+            stagger?: boolean | undefined;
+        } | undefined;
+    };
+    blocks: {
+        id: `blk_${string}`;
+        type: string;
+        v: number;
+        fields: Record<string, unknown>;
+        column?: number | undefined;
+        label?: string | undefined;
+        hidden?: boolean | undefined;
+        variant?: string | undefined;
+        style?: {
+            colorTheme?: "light" | "light-accent" | "dark" | "dark-accent" | "brand" | undefined;
+            padding?: {
+                d: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+                t?: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
+                m?: "none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
+            } | undefined;
+            radius?: "none" | "sm" | "md" | "lg" | "xl" | "full" | undefined;
+            border?: "none" | "subtle" | "strong" | undefined;
+            shadow?: "none" | "sm" | "md" | "lg" | undefined;
+            align?: {
+                d: "start" | "center" | "end";
+                t?: "start" | "center" | "end" | undefined;
+                m?: "start" | "center" | "end" | undefined;
+            } | undefined;
+            imageTreatment?: "none" | "rounded" | "arch" | "circle" | "blob" | "duotone" | "grain" | "frame" | undefined;
+            animation?: {
+                entrance: "none" | "fade" | "rise" | "slide" | "zoom" | "clip";
+                stagger?: boolean | undefined;
+            } | undefined;
+            typography?: Record<string, "small" | "display" | "h1" | "h2" | "h3" | "h4" | "lead" | "body" | "eyebrow"> | undefined;
+        } | undefined;
+    }[];
+    preset?: string | undefined;
+    label?: string | undefined;
+    anchor?: string | undefined;
+    locked?: boolean | undefined;
+    hidden?: boolean | undefined;
+} | undefined>;
+
+/** Join class names, skipping falsy values. */
+declare function cx(...parts: (string | false | null | undefined | 0)[]): string;
+/** A CSSProperties-compatible object of custom properties (`{"--x": 1}`). */
+type CssVars = Record<`--${string}`, string | number>;
+declare module "react" {
+    interface CSSProperties {
+        [key: `--${string}`]: string | number | undefined;
+    }
+}
+
+/** `acme/map` → `acme-map`. */
+declare const blockTypeClass: (type: string) => string;
+/** `os-align-center os-talign-center os-malign-start` (inheritance applied). */
+declare function alignClasses(align: Responsive<Align>): string;
+/** Wrapper classes + vars for a block's token style overrides. */
+declare function blockStyleProps(style: BlockStyle | undefined, mode: RenderMode): {
+    className: string;
+    vars: CssVars;
+    attrs: Record<string, string>;
+};
+interface BlockViewProps {
+    block: Block;
+    /** The containing section (absent for standalone renders such as email/OG). */
+    section?: Section;
+}
+/**
+ * Render one block through the registry: migrate if stale, validate fields, wrap in a
+ * `.os-block` container (container-query context, token style overrides, `data-os-id`).
+ */
+declare function BlockView({ block, section }: BlockViewProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element | null | undefined;
+
+/** Small stable hash (FNV-1a, base36) used for dismissal / frequency keys. */
+declare function shortHash(text: string): string;
+/** Site-wide announcement bar; dismissal (per message) is remembered by the `announcement` behavior. */
+declare function AnnouncementBar({ announcement, }: {
+    announcement: Announcement | null | undefined;
+}): react.JSX.Element | null;
+/** Site footer: the site's footer section inside a `<footer>` landmark, plus optional extras. */
+declare function Footer({ site, children }: {
+    site: Site;
+    children?: ReactNode;
+}): react.JSX.Element;
+type PopupTrigger = {
+    type: "time";
+    seconds: number;
+} | {
+    type: "scroll";
+    percent: number;
+} | {
+    type: "exit";
+};
+interface PopupProps {
+    /** Stable id; also the frequency-cap storage key. */
+    id: string;
+    trigger: PopupTrigger;
+    /** Show at most once every N days per visitor (default 7; 0 = every visit). */
+    frequencyDays?: number;
+    /** Accessible title (rendered as the dialog heading). */
+    title: string;
+    colorTheme?: ColorTheme;
+    children?: ReactNode;
+}
+/**
+ * Promotional popup as a native `<dialog>` opened by the `popup` behavior on a time, scroll or
+ * exit-intent trigger, capped per visitor via localStorage. Esc and the close button dismiss it.
+ */
+declare function Popup({ id, trigger, frequencyDays, title, colorTheme, children, }: PopupProps): react.JSX.Element;
+/** Trigger props for the `<Popup>` from the site's pop-up settings. */
+declare function popupTrigger(popup: Popup$1): PopupTrigger;
+/**
+ * The site-wide pop-up from `site.popup` (heading, words, image, button, newsletter signup),
+ * rendered with `<Popup>`. The newsletter form is the registered `newsletter` block, so it posts
+ * to the Hub exactly like one placed on a page. Content changes reset the visitor frequency cap
+ * (the dialog id hashes the heading).
+ */
+declare function SitePopup({ popup }: {
+    popup: Popup$1 | null | undefined;
+}): react.JSX.Element | null;
+
+/**
+ * Collection data for blocks that list items (summary, events, product, social feed).
+ *
+ * By default blocks read `doc.collections` from the {@link RenderContext}. Hosts that hold
+ * collection data elsewhere provide it through `CollectionsContext`: site-kit passes the parsed
+ * content collections, the build time (`now`) and build-time social feeds; Studio passes the
+ * items it has loaded. Values given here take precedence over the document.
+ */
+interface CollectionsValue {
+    /** Items by collection name, then slug. Defaults to `doc.collections`. */
+    collections?: Record<string, Record<string, CollectionItem>>;
+    /** `_collection.json` per collection. Defaults to `doc.collectionConfigs`. */
+    configs?: Record<string, CollectionConfig>;
+    /**
+     * Reference time for "upcoming" filters and scheduled items. Static builds pass the build
+     * time so output is deterministic. Defaults to the current time.
+     */
+    now?: Date | string;
+    /**
+     * Include drafts and not-yet-due scheduled items. Defaults to `true` in the Studio editor and
+     * previews and `false` in production.
+     */
+    includeDrafts?: boolean;
+    /** Build-time social feed posts, keyed by {@link feedKey} (`instagram:juniperyoga`). */
+    feeds?: Record<string, SocialFeedPost[]>;
+}
+/** One post of a build-time social feed (fetched by site-kit with the owner's authorization). */
+interface SocialFeedPost {
+    /** Link to the post on the network (https). */
+    url: string;
+    image: ImageValue;
+    caption?: string;
+    /** ISO date or date-time. */
+    date?: string;
+}
+declare const CollectionsContext: react.Context<CollectionsValue | undefined>;
+/** Key for {@link CollectionsValue.feeds}: `network:handle`, lowercased, without a leading `@`. */
+declare function feedKey(network: string, handle: string): string;
+interface ResolvedCollections {
+    collections: Record<string, Record<string, CollectionItem>>;
+    configs: Record<string, CollectionConfig>;
+    now: Date;
+    includeDrafts: boolean;
+    feeds: Record<string, SocialFeedPost[]>;
+}
+/** Collection data for the current render (context value merged over the site document). */
+declare function useCollections(): ResolvedCollections;
+/** The item's primary date: post/episode/project date or event start. */
+declare function itemDate(item: CollectionItem): string | undefined;
+/** Published (or scheduled and due) at `now`. */
+declare function isLive(item: CollectionItem, now: Date): boolean;
+/**
+ * An event is upcoming until it ends. Date-only events (`2026-11-14`) count as upcoming for
+ * that whole day in the event's own time zone (`timezone`, else UTC).
+ */
+declare function isUpcoming(item: CollectionItem, now: Date): boolean;
+/** How far ahead (and back, for past events) repeating events are listed. */
+declare const RECURRENCE_HORIZON_DAYS = 366;
+/** A repeating event shown at its next date (or its last one, once the series is over). */
+declare function nextOccurrence(item: CollectionItem, now: Date): CollectionItem;
+interface QueryOptions {
+    now?: Date;
+    includeDrafts?: boolean;
+}
+/**
+ * Items a `reference` field selects: explicit picks (in their order) or the filter, then sort
+ * and limit. Drafts and not-yet-due scheduled items are excluded unless `includeDrafts`.
+ * `filter.upcoming: true` keeps events that haven't ended; `false` keeps past events.
+ */
+declare function queryCollection(ref: ReferenceValue, collections: Record<string, Record<string, CollectionItem>>, opts?: QueryOptions): CollectionItem[];
+/** `queryCollection` bound to the current render's collections, time and draft policy. */
+declare function useCollectionQuery(ref: ReferenceValue): CollectionItem[];
+
+/** Header variants whose navigation is always behind the menu button. */
+declare const DRAWER_VARIANTS: readonly HeaderVariant[];
+interface EffectiveHeader extends Header$1 {
+    hidden: boolean;
+    /** The header overlays the first section (variant `transparent-overlay` or transparent-on-hero). */
+    overlay: boolean;
+}
+/** Merge the site header with a page's override. */
+declare function effectiveHeader(site: Site, page: Page | undefined): EffectiveHeader;
+interface ResolvedNavLeaf {
+    kind: "leaf";
+    label: string;
+    href: string;
+    current: boolean;
+    newTab: boolean;
+}
+interface ResolvedNavFolder {
+    kind: "folder";
+    label: string;
+    current: boolean;
+    items: ResolvedNavLeaf[];
+}
+type ResolvedNav = ResolvedNavLeaf | ResolvedNavFolder;
+/** Resolve the nav tree (hidden entries and dangling pages dropped; buttons excluded). */
+declare function resolveNav(nav: readonly NavItem[], doc: SiteDocument | undefined, basePath: string, currentId: string | undefined): ResolvedNav[];
+interface HeaderProps {
+    site: Site;
+    page?: Page | undefined;
+    /** Color theme of the first section; used when the header overlays it. */
+    heroTheme?: ColorTheme | undefined;
+    /** Show the cart button (sites with commerce). */
+    cart?: boolean;
+}
+/**
+ * Site header in one of eight layouts, with sticky / transparent-on-hero modes, nav folders
+ * (`<details>`, so they work without JavaScript) and a mobile menu (slide, fullscreen or
+ * dropdown) driven by the `menu` behavior. Without JavaScript the mobile menu is shown inline.
+ */
+declare function Header({ site, page, heroTheme, cart }: HeaderProps): react.JSX.Element | null;
+
+/**
+ * Page metadata helpers shared by `renderPageHtml` and the Studio (titles, descriptions, URLs,
+ * compiled styles). Kept apart from `html.ts` so importing them never pulls `react-dom/server`
+ * into a browser bundle.
+ */
+
+declare const escapeHtml: (s: string) => string;
+/** JSON for a `<script>` element: `<`, U+2028/9 escaped so content can never close the tag. */
+declare function jsonForScript(value: unknown): string;
+/** `compileStyles` memoised per styles object (site-kit renders many pages per build). */
+declare function compiledStylesFor(styles: Styles): CompiledStyles;
+/** The site's absolute URL (with base path), ending in `/`. */
+declare function siteUrlFor(doc: SiteDocument, override?: string): string;
+/** `<title>`: SEO title, else page title, through the site's `%s` template (home: site title). */
+declare function pageTitle(doc: SiteDocument, page: Page): string;
+declare function pageDescription(doc: SiteDocument, page: Page): string | undefined;
+
+interface RenderPageHtmlOptions {
+    doc: SiteDocument;
+    /** Page id, or a page object (collection item pages, unsaved drafts). */
+    pageId: string | Page;
+    mode?: "production" | "preview";
+    /** Site base path (`/maya-yoga` on a GitHub project site); `""` at a domain root. */
+    basePath?: string;
+    imageMap?: ImageMap;
+    /** Hub origin for forms/newsletter/analytics/cart (default: `config.hub`). */
+    hubUrl?: string;
+    /** Where behavior modules are served (default `<basePath>/_os/behaviors`). */
+    behaviorsUrl?: string;
+    /**
+     * Absolute site URL including the base path, for canonical and Open Graph URLs (default:
+     * `https://<customDomain>` or `config.deploy.url`).
+     */
+    siteUrl?: string;
+    /** Structured data emitted as `<script type="application/ld+json">`. */
+    jsonLd?: object | object[];
+    /**
+     * Font stylesheet URLs. Default: the pairing's Google Fonts URL (previews). Published sites
+     * pass self-hosted Fontsource CSS; `[]` disables web fonts.
+     */
+    fontStylesheets?: string[];
+    /** Link the stylesheets instead of inlining them (site-kit serves them as cacheable files). */
+    stylesheets?: {
+        base?: string;
+        tokens?: string;
+    };
+    /** Extra trusted markup appended to `<head>` (site-kit feed links etc.). */
+    extraHead?: string;
+}
+/**
+ * Render a complete HTML document for a page: head (title, meta, Open Graph, canonical, JSON-LD,
+ * fonts, token CSS, base CSS, custom CSS, head injection), the rendered body, and behavior
+ * scripts only for behaviors the page actually uses. No React runtime ships.
+ */
+declare function renderPageHtml(opts: RenderPageHtmlOptions): string;
+/**
+ * Behaviors a page needs: pass rendered HTML, or render options (the page is rendered first).
+ * Includes `beacon` for production renders with analytics on.
+ */
+declare function behaviorsForPage(input: string | RenderPageHtmlOptions): BehaviorName[];
+
+/** Widths offered for remote images that support on-the-fly resizing (Unsplash, imgix). */
+declare const REMOTE_WIDTHS: readonly [480, 640, 768, 960, 1080, 1440, 1920, 2400];
+interface ImgProps {
+    /** A media path / URL, or a full image value (src + alt + focal + dimensions). */
+    src: string | ImageValue;
+    /** Required unless `src` is an image value carrying `alt`. `""` marks a decorative image. */
+    alt?: string;
+    /** `sizes` attribute; describe the rendered width so the browser picks the right file. */
+    sizes?: string;
+    width?: number;
+    height?: number;
+    /** Focal point `[x, y]` (0..1); drives `object-position` when the image is cropped. */
+    focal?: FocalPoint;
+    /** Crop to an aspect ratio (`4:5`, `16:9`); `original` keeps the intrinsic ratio. */
+    aspect?: AspectRatio;
+    /**
+     * Image treatment. Omitted: the site's default treatment (from Site Styles). `"none"` opts out.
+     */
+    treatment?: ImageTreatment;
+    fit?: "cover" | "contain";
+    /**
+     * Fill the parent's height, cropping at the focal point (grid-mode cells: the cell's rows set
+     * the height, the image never stretches the row).
+     */
+    fill?: boolean;
+    /** Above-the-fold image: eager load + high fetch priority. */
+    priority?: boolean;
+    className?: string;
+}
+interface Resolved {
+    src: string;
+    srcset?: string | undefined;
+    sources: {
+        type: string;
+        srcset: string;
+    }[];
+    width?: number | undefined;
+    height?: number | undefined;
+    placeholder?: string | undefined;
+}
+/** Build a srcset for Unsplash/imgix-style URLs by rewriting the `w` query parameter. */
+declare function remoteSrcset(src: string, intrinsicWidth?: number): string | undefined;
+/** Resolve an image source through the image map, the media library, then raw fallbacks. */
+declare function resolveImage(src: string, opts?: {
+    imageMap?: ImageMap | undefined;
+    doc?: SiteDocument | undefined;
+    basePath?: string;
+    width?: number | undefined;
+    height?: number | undefined;
+}): Resolved;
+/**
+ * Above-the-fold images: the sources `SectionView` picked for the page's first section (the
+ * first two in reading order, background first — the likely LCP element). Those load eagerly
+ * with `fetchpriority="high"`; every other image loads lazily unless `priority` is set. A plain
+ * value computed from the section, so rendering stays pure.
+ */
+type AboveFold = ReadonlySet<string>;
+declare const AboveFoldContext: react.Context<AboveFold | null>;
+/**
+ * Responsive image. Reads the `ImageResolverContext` map (AVIF/WebP sources, srcset, intrinsic
+ * size, blurred placeholder), always emits width/height when known, crops with
+ * `object-position` at the focal point, and applies image-treatment classes.
+ */
+declare function Img(props: ImgProps): react.JSX.Element;
+
+/** Emit `--{p}{name}` for each breakpoint from a responsive value (inheritance applied). */
+declare function responsiveVars<T>(name: string, value: Responsive<T> | undefined, map: (v: T) => string | number): CssVars;
+/** Section-level vars: padding, min height. */
+declare function sectionStyleVars(style: SectionStyle): CssVars;
+/** Stack-mode container vars: column templates per breakpoint. */
+declare function stackVars(layout: StackLayout): CssVars;
+/**
+ * Per-column stacking order at tablet/mobile (`layout.order`, FR-13). Mobile inherits the
+ * tablet order. Returns `{ "--to": n, "--mo": n }` for desktop column `index`.
+ */
+declare function stackColumnVars(layout: StackLayout, index: number): CssVars;
+/** Group a stack section's blocks by desktop column (out-of-range columns land in the last). */
+declare function blocksByColumn(layout: StackLayout, blocks: readonly Block[]): Block[][];
+/** Grid container vars: row counts per breakpoint. */
+declare function gridVars(layout: GridLayout): CssVars;
+
+/**
+ * Inline vars for one grid item: `--x/--y/--w/--h/--z`, `--tx…`, `--mx…`, bleed lines
+ * (`--cs/--ce`) and pinned row lines (`--rs/--re`).
+ */
+declare function gridItemVars(layout: GridLayout, id: string, mobileFallback?: Record<string, GridRect>): CssVars;
+/** Total rows actually needed for mobile when fallback rects extend past the stored count. */
+declare function mobileRows(layout: GridLayout, fallback: Record<string, GridRect>): number;
+/** CSS value for a color value: token → `var(--os-color-…)`, exact colors pass through. */
+declare function colorValue(value: string): string;
+
+/** Normalise a base path: `""`, `"/"` → `""`; `"repo/"` → `"/repo"`. */
+declare function normalizeBasePath(basePath: string | undefined): string;
+/** URL path of a page: home is `/`, others end with a slash (`/about/`). */
+declare function pagePath(page: Pick<Page, "slug">, basePath?: string): string;
+/** URL path of a collection item: `/journal/opening-day/`. */
+declare function itemPath(collection: string, slug: string, basePath?: string): string;
+/** Public URL of a media source: repo paths get the base path, remote URLs pass through. */
+declare function mediaUrl(src: string, basePath?: string): string;
+/** Prefix a site-relative path (`/schedule`) with the base path; leave everything else. */
+declare function withBase(href: string, basePath?: string): string;
+interface ResolvedLink {
+    href: string;
+    /** Open in a new tab (adds `target="_blank" rel="noopener"`). */
+    newTab: boolean;
+    /** The target no longer exists (deleted page/section). */
+    broken: boolean;
+    external: boolean;
+}
+interface LinkResolveOptions {
+    doc?: SiteDocument | undefined;
+    basePath?: string;
+    /** The page being rendered: anchors to its own sections become `#fragment`. */
+    currentPageId?: string | undefined;
+}
+/** In-page fragment for a section: its `anchor` if set, else its id. */
+declare function sectionFragment(section: {
+    id: string;
+    anchor?: string | undefined;
+}): string;
+/** Resolve a link target (page, collection item, URL, email, phone, file, anchor) to an href. */
+declare function resolveLink(link: Link$1, opts?: LinkResolveOptions): ResolvedLink;
+interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    to: Link$1;
+    children?: ReactNode;
+}
+/** An `<a>` for a structured link, resolved against the current site and base path. */
+declare function Link({ to, children, ...rest }: LinkProps): react.JSX.Element;
+
+interface PageViewProps {
+    doc: SiteDocument;
+    /** A page id in `doc.pages`, or a page object (e.g. an unsaved draft or a collection item page). */
+    page: string | Page;
+    mode?: RenderMode;
+    basePath?: string;
+    imageMap?: ImageMap;
+    hubUrl?: string;
+    /** Studio hooks (canvas selection affordances). */
+    editor?: EditorHooks;
+    /** Rendered after the footer (popups, cart drawer mount points). */
+    extras?: ReactNode;
+}
+/** Resolve the page prop to a page object; throws for unknown ids. */
+declare function resolvePage(doc: SiteDocument, page: string | Page): Page;
+/**
+ * A whole page: skip link, announcement bar, header, the page's sections in `<main>`, footer.
+ * The same component renders the Studio canvas (`mode: "editor"`), the Hub preview and the
+ * published site.
+ */
+declare function PageView(props: PageViewProps): react.JSX.Element;
+
+type ButtonRole = "primary" | "secondary" | "tertiary";
+interface ButtonProps {
+    /** Link target; omit for a `<button>` (e.g. a form submit). */
+    to?: Link$1;
+    role?: ButtonRole;
+    type?: "button" | "submit";
+    className?: string;
+    children: ReactNode;
+    /** Extra attributes (data-os-*, aria-*). */
+    attrs?: Record<string, string | undefined>;
+}
+/**
+ * A button styled by the Site Styles button system (`--os-button-<role>-*`). Renders an `<a>`
+ * for links, a `<button>` otherwise.
+ */
+declare function Button({ to, role, type, className, children, attrs, }: ButtonProps): react.JSX.Element;
+declare function networkLabel(network: string): string;
+/** Small outline icon for a social network (inherits `currentColor`). */
+declare function SocialIcon({ network }: {
+    network: string;
+}): react.JSX.Element;
+/** A row of social profile links with accessible names. */
+declare function SocialLinks({ profiles, className, }: {
+    profiles: readonly SocialProfile[];
+    className?: string;
+}): react.JSX.Element | null;
+
+interface RecurrenceRule {
+    freq: "DAILY" | "WEEKLY" | "MONTHLY" | "YEARLY";
+    interval: number;
+    /** Weekly days, e.g. ["TU", "TH"]. */
+    byDay: string[];
+    /** Monthly "nth weekday" (1–5 or -1), from BYDAY=2TU. */
+    nth?: {
+        n: number;
+        day: string;
+    };
+    byMonthDay?: number;
+    count?: number;
+    /** Last allowed date, YYYY-MM-DD. */
+    until?: string;
+}
+declare function parseRecurrence(rule: string): RecurrenceRule | null;
+/**
+ * Occurrence dates (YYYY-MM-DD) of a rule starting on `start`, in order.
+ * - `from` / `through` bound the dates returned (inclusive);
+ * - `max` caps how many are returned (counted from `from`, never from the first date);
+ * - COUNT is counted from the first date, as RFC 5545 says (DTSTART is the first occurrence).
+ * Without COUNT, the walk jumps straight to `from`, so a series that started years ago costs the
+ * same as a new one.
+ */
+declare function occurrenceDates(rule: string | RecurrenceRule, start: string, options?: {
+    from?: string;
+    through?: string;
+    max?: number;
+}): string[];
+/** The same event moved to another date (local time of day and length kept). */
+declare function eventOn(item: Extract<CollectionItem, {
+    kind: "events";
+}>, date: string): typeof item;
+/**
+ * Repeating events as one item per occurrence between `from` and `through` (YYYY-MM-DD),
+ * at most `perEvent` each: the earliest ones, or with `newest` the most recent ones (for past
+ * lists). Other items pass through unchanged.
+ */
+declare function expandOccurrences(items: CollectionItem[], window: {
+    from: string;
+    through: string;
+    perEvent?: number;
+    newest?: boolean;
+}): CollectionItem[];
+/** React key for a listed item (repeating events share a slug). */
+declare function itemKey(item: CollectionItem): string;
+
+/** Class for a typography preset: `os-type-h2`. */
+declare const typeClass: (preset: TypePreset | "button" | "nav") => string;
+interface RichTextProps {
+    doc: RichTextDoc | null | undefined;
+    className?: string;
+    /** Element wrapping the flow (default `div`). */
+    as?: "div" | "section" | "article";
+}
+/**
+ * Render a rich-text document (arch §3.5) to semantic HTML. Headings and paragraphs carry
+ * typography preset classes; links are base-path aware; no inline styles except token
+ * highlight colors.
+ */
+declare function RichText({ doc, className, as: Tag }: RichTextProps): react.JSX.Element | null;
+
+/** True for the first section of a page (its background image loads eagerly). */
+declare const FirstSectionContext: react.Context<boolean>;
+/** Color/gradient backgrounds become a `--bg` var; image/video become a layer element. */
+declare function backgroundVars(bg: SectionBackground | undefined): CssVars;
+declare function SectionBackgroundLayer({ background, }: {
+    background: SectionBackground | undefined;
+}): react.JSX.Element | null;
+interface SectionViewProps {
+    section: Section;
+    /** Element to render (`div` for the footer's inner section). */
+    as?: "section" | "div";
+    /** Extra classes on the section element. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * A page section: color-theme wrapper, background layer, then the stack or grid body. Every
+ * per-instance value is an inline custom property; classes come from the shared stylesheet.
+ */
+declare function SectionView({ section, as: Tag, className }: SectionViewProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element | null | undefined;
+
+/**
+ * @omniharmonic/openspace-renderer — the one renderer (ADR-3). React components that turn OpenSpace content
+ * into HTML for the Studio canvas, the Hub preview, site-kit builds and OG/email generation.
+ * Published pages ship no React runtime: interactivity comes from vanilla `data-os-behavior`
+ * modules (see `./behaviors-manifest` and the `@omniharmonic/openspace-renderer/node` entry for files).
+ */
+declare const name = "@omniharmonic/openspace-renderer";
+
+export { type AboveFold, AboveFoldContext, AnnouncementBar, BehaviorName, BlockFieldsContext, BlockRegistryContext, BlockView, type BlockViewProps, Button, type ButtonProps, type ButtonRole, CollectionsContext, type CollectionsValue, type CssVars, DRAWER_VARIANTS, EditorContext, type EditorHooks, type EffectiveHeader, FirstSectionContext, Footer, Header, type HeaderProps, type ImageMap, ImageResolverContext, Img, type ImgProps, Link, type LinkProps, type LinkResolveOptions, PageView, type PageViewProps, Popup, type PopupProps, type PopupTrigger, type QueryOptions, RECURRENCE_HORIZON_DAYS, REMOTE_WIDTHS, type RecurrenceRule, RenderContext, type RenderContextValue, type RenderMode, type RenderPageHtmlOptions, type RendererBlockDefinition, type RendererBlockRegistry, type ResolvedCollections, type ResolvedImage, type ResolvedImageSource, type ResolvedLink, RichText, type RichTextHookArgs, type RichTextProps, SectionBackgroundLayer, SectionContext, SectionView, type SectionViewProps, SitePopup, type SocialFeedPost, SocialIcon, SocialLinks, alignClasses, backgroundVars, behaviorsForPage, blockStyleProps, blockTypeClass, blocksByColumn, collectImageSrcs, colorValue, compiledStylesFor, cx, effectiveHeader, escapeHtml, eventOn, expandOccurrences, feedKey, fieldPathOf, getBlock, globalRegistry, gridItemVars, gridVars, isLive, isUpcoming, itemDate, itemKey, itemPath, jsonForScript, listBlocks, mediaUrl, mobileRows, name, networkLabel, nextOccurrence, normalizeBasePath, occurrenceDates, pageDescription, pagePath, pageTitle, parseRecurrence, popupTrigger, queryCollection, registerBlocks, remoteSrcset, renderPageHtml, resolveImage, resolveLink, resolveNav, resolvePage, responsiveVars, sectionFragment, sectionStyleVars, shortHash, siteUrlFor, stackColumnVars, stackVars, typeClass, unregisterBlocks, useCollectionQuery, useCollections, useEditor, useImageMap, useRenderContext, withBase };