@cogenta/theme-kit 0.3.2

package/dist/chrome.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The chrome extension point — the one piece of a rendered page that used to
+ * live outside every theme entirely: `cogenta serve` used to hand-write the
+ * `<header>`/`<footer>` markup itself, hardcoded to one theme's CSS classes,
+ * which is exactly what made a second theme impossible to install without
+ * either fighting the first theme's chrome or losing chrome altogether.
+ *
+ * A theme now owns its own header and footer, the same way it owns its own
+ * block layouts — `cogenta serve` resolves the navigation data and the
+ * CMS-wide branding fragment (never a theme's business, see `brandingHtml`
+ * below) and hands both to the active theme's `renderChrome`.
+ */
+import type { ImageSource } from './contract.js';
+import { type HtmlElement } from './html.js';
+/**
+ * The site's own visual identity, as the appearance screen already stores it
+ * — logo, dark-scheme logo, favicon (contract D `theme@1.3`).
+ *
+ * Optional on `ChromeInput` on purpose: a host that predates this field, and
+ * a theme that chooses to ignore it, both keep the pre-1.3 behaviour of
+ * setting the site *name* as text. A theme that does use it shows `logo`
+ * **instead of** the name, and keeps the name as the image's accessible name
+ * — never both, and never a logo with no accessible name.
+ *
+ * `logo`/`logoDark` are `ImageSource`s, not raw URLs, so a logo gets the same
+ * `srcset` and intrinsic-size guarantees every other image on the page has.
+ * `logoDark` is a *second* source, never a replacement: choosing between the
+ * two is a `prefers-color-scheme` decision the browser makes at render time,
+ * never one the server takes on the visitor's behalf — the server has no way
+ * of knowing which scheme the visitor is in.
+ *
+ * `faviconUrl` travels here so a site's whole identity is one object, but it
+ * is the *host* that writes `<link rel="icon">`: a theme owns `<header>` and
+ * `<footer>`, never `<head>`.
+ */
+export interface ChromeBrand {
+    /** The site's own name — what a theme shows when there is no logo, and the logo's accessible name when there is one. */
+    readonly name: string;
+    /** `null` when no logo is set, when the chosen media is gone, or when it is not an image. */
+    readonly logo: ImageSource | null;
+    /** The dark-scheme variant, or `null`. Offered beside `logo`, never instead of it. */
+    readonly logoDark: ImageSource | null;
+    /** Site-relative URL of the favicon, or `null` for the host's own default. Rendered by the host, not by a theme. */
+    readonly faviconUrl: string | null;
+}
+export interface ChromeNavLink {
+    readonly label: string;
+    /** `null` for a `submenu-placeholder` — an unlinked heading, not a dead link (a dead link is dropped before it reaches here). */
+    readonly href: string | null;
+    readonly openInNewTab: boolean;
+    readonly kind: string;
+    /** The HTML `title` attribute (a tooltip), or `null`. Never this link's visible label. */
+    readonly title: string | null;
+}
+/** A labelled destination — a social profile, a header call-to-action. Nothing more, on purpose: contract D never carries an icon choice or an emphasis for these, only a URL and the words that name it. */
+export interface ChromeLink {
+    readonly label: string;
+    readonly href: string;
+}
+export interface ChromeInput {
+    readonly site: {
+        readonly name: string;
+    };
+    readonly locale: string;
+    /** `/`, already locale-resolved — the target of the site's own "home" link. */
+    readonly homeHref: string;
+    readonly headerNav: readonly ChromeNavLink[];
+    readonly footerNav: readonly ChromeNavLink[];
+    /**
+     * Cogenta's own credit, or its white-label replacement, or `''` for
+     * neither (fiche L21 task 8) — already-escaped HTML, computed once by
+     * `cogenta serve` from a site-wide setting no theme may reinterpret. A
+     * theme places this fragment somewhere inside its own footer; it must not
+     * alter or drop it on its own initiative.
+     */
+    readonly brandingHtml: string;
+    /**
+     * The site's own identity (contract D `theme@1.3`). Absent means the
+     * pre-1.3 behaviour — the site name, as text — which is what a host that
+     * never wired this and a site that never uploaded a logo both get.
+     */
+    readonly brand?: ChromeBrand;
+    /**
+     * `general.tagline` (contract D `theme@1.4`), in the page's own locale.
+     * Optional and additive: a theme that never reads it, and a site that has
+     * never set one, both render exactly as they did under `theme@1.3` — this
+     * is what makes the version bump minor rather than major. A theme that does
+     * show it places it beside the brand mark or in the footer's own "about"
+     * column; it is prose, not a second `<h1>`.
+     */
+    readonly tagline?: string;
+    /**
+     * `general.socialLinks` (contract D `theme@1.4`) — the site's own social
+     * profiles, already resolved to `{label, href}` pairs. Absent or empty
+     * means "nothing configured", identical to a pre-1.4 render. A theme is
+     * free to render these itself, but `renderSocialLinks` below is the shared,
+     * icon-carrying way every built-in theme does it, so five themes do not
+     * each draw their own X/Mastodon/Bluesky glyphs from scratch.
+     */
+    readonly social?: readonly ChromeLink[];
+    /**
+     * `general.footerNote` (contract D `theme@1.4`) — a short, site-wide line
+     * an editor writes once (a legal mention, an "about" sentence, an address)
+     * and every theme's footer is free to show as its own short "about" column.
+     * Plain text, already the caller's to escape like any other string field —
+     * this module carries no HTML-bearing fields (R3 applies to a theme's own
+     * markup exactly as it does to a block's).
+     */
+    readonly footerNote?: string;
+    /**
+     * The first link of the menu assigned to the `header-action` location
+     * (`resolveChromeExtras`, `@cogenta/cli`), if a site has assigned one —
+     * absent otherwise. A theme that shows it renders a single button-styled
+     * link at the end of its header nav ("Book a demo", "Get started",
+     * "Contact"); a theme that ignores it loses nothing a pre-1.4 site had.
+     */
+    readonly headerAction?: ChromeLink;
+}
+export interface ChromeResult {
+    readonly header: string;
+    readonly footer: string;
+}
+/**
+ * The site's logo, as one already-escaped HTML fragment — or `null` when the
+ * site has no logo, which is the signal to fall back to the site name in
+ * text.
+ *
+ * Shared here rather than written five times: the light/dark pair is a
+ * `<picture>` with a `prefers-color-scheme` `<source>`, and getting that
+ * wrong (picking a variant server-side, or dropping the accessible name) is
+ * the same mistake in every theme. What each theme still owns is *where* the
+ * mark goes and how it is sized — this returns markup, never layout.
+ *
+ * `alt` is the site name, always written: a logo announced by its file name
+ * is the WCAG 1.1.1 failure this helper exists to make impossible.
+ */
+export declare function renderBrandMark(brand: ChromeBrand | undefined, options?: {
+    readonly className?: string;
+}): string | null;
+/**
+ * `general.socialLinks` (contract D `theme@1.4`), as a `<ul>` of icon links —
+ * `null` when there is nothing to show, so a theme can write
+ * `renderSocialLinks(input.social)` straight into its footer without a
+ * conditional of its own.
+ *
+ * Every icon carries a visually-hidden text label (`cg-visually-hidden` — a
+ * theme that renders this must define that class, the standard
+ * clip-to-1px-and-hide technique, since `@cogenta/theme-kit` ships no CSS of
+ * its own) so the link's accessible name is still the platform *and* the
+ * label the site owner chose (`aria-label` would drop the wording an editor
+ * wrote; hidden text keeps it). `rel="me noopener noreferrer"` on every link:
+ * `me` is the [IndieWeb/Mastodon verification
+ * relation](https://indieweb.org/rel-me), harmless everywhere else, and the
+ * other two are the same external-link protection every theme already gives
+ * an off-site `<a>`.
+ */
+export declare function renderSocialLinks(social: readonly ChromeLink[] | undefined, options?: {
+    readonly className?: string;
+    readonly itemClassName?: string;
+}): HtmlElement | null;
+//# sourceMappingURL=chrome.d.ts.map

package/dist/chrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.d.ts","sourceRoot":"","sources":["../src/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAmB,KAAK,WAAW,EAAK,MAAM,WAAW,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B,wHAAwH;IACxH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACjC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IACrC,oHAAoH;IACpH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iIAAiI;IACjI,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,6MAA6M;AAC7M,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAA;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAA;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAA;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,MAAM,GAAG,IAAI,CAef;AA4JD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,EACzC,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7E,WAAW,GAAG,IAAI,CAkBpB"}

package/dist/chrome.js

@@ -0,0 +1,198 @@
+/**
+ * The chrome extension point — the one piece of a rendered page that used to
+ * live outside every theme entirely: `cogenta serve` used to hand-write the
+ * `<header>`/`<footer>` markup itself, hardcoded to one theme's CSS classes,
+ * which is exactly what made a second theme impossible to install without
+ * either fighting the first theme's chrome or losing chrome altogether.
+ *
+ * A theme now owns its own header and footer, the same way it owns its own
+ * block layouts — `cogenta serve` resolves the navigation data and the
+ * CMS-wide branding fragment (never a theme's business, see `brandingHtml`
+ * below) and hands both to the active theme's `renderChrome`.
+ */
+import { escapeAttribute, h } from './html.js';
+/**
+ * The site's logo, as one already-escaped HTML fragment — or `null` when the
+ * site has no logo, which is the signal to fall back to the site name in
+ * text.
+ *
+ * Shared here rather than written five times: the light/dark pair is a
+ * `<picture>` with a `prefers-color-scheme` `<source>`, and getting that
+ * wrong (picking a variant server-side, or dropping the accessible name) is
+ * the same mistake in every theme. What each theme still owns is *where* the
+ * mark goes and how it is sized — this returns markup, never layout.
+ *
+ * `alt` is the site name, always written: a logo announced by its file name
+ * is the WCAG 1.1.1 failure this helper exists to make impossible.
+ */
+export function renderBrandMark(brand, options = {}) {
+    if (brand === undefined || brand.logo === null)
+        return null;
+    const classAttr = options.className === undefined ? '' : ` class="${escapeAttribute(options.className)}"`;
+    const img = `<img${classAttr} src="${escapeAttribute(brand.logo.src)}"` +
+        `${brand.logo.srcset === '' ? '' : ` srcset="${escapeAttribute(brand.logo.srcset)}"`}` +
+        ` width="${brand.logo.width}" height="${brand.logo.height}"` +
+        ` alt="${escapeAttribute(brand.name)}" decoding="async">`;
+    if (brand.logoDark === null)
+        return img;
+    const darkSet = brand.logoDark.srcset === '' ? brand.logoDark.src : brand.logoDark.srcset;
+    return (`<picture><source srcset="${escapeAttribute(darkSet)}" media="(prefers-color-scheme: dark)">` +
+        `${img}</picture>`);
+}
+/** A circle, as two arcs — every icon below is built from this and `roundedRect`, never copied vector data. */
+function circlePath(cx, cy, r) {
+    return `M${cx - r} ${cy}A${r} ${r} 0 1 0 ${cx + r} ${cy}A${r} ${r} 0 1 0 ${cx - r} ${cy}Z`;
+}
+function roundedRect(x, y, w, h, r) {
+    return (`M${x + r} ${y}H${x + w - r}A${r} ${r} 0 0 1 ${x + w} ${y + r}V${y + h - r}` +
+        `A${r} ${r} 0 0 1 ${x + w - r} ${y + h}H${x + r}A${r} ${r} 0 0 1 ${x} ${y + h - r}` +
+        `V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`);
+}
+/**
+ * One or more **groups** of `d` strings per platform, each group rendered as
+ * its own `<path>` element with `fill-rule="evenodd"` — every icon's own
+ * `<svg>` root also sets it, but that alone is not what makes a nested
+ * contour a ring rather than a solid blob: `evenodd` only cancels overlap
+ * *within a single path's own subpaths*, never across sibling `<path>`
+ * elements. Two contours meant to punch a hole in each other (instagram's
+ * frame and lens, YouTube's frame around its play triangle, threads' loop,
+ * the generic fallback's two chain-link rings) must be joined into **one**
+ * group's `d`; a shape meant to sit solid *beside* another (linkedin's dot,
+ * stem and bowl; github's head and body; instagram's own flash dot) stays
+ * its own group so it is never accidentally subtracted from a neighbour it
+ * happens to overlap.
+ */
+const SOCIAL_ICON_PATHS = {
+    x: [['M4 4l6.7 8.1L4.2 20H7l5-6.1L17 20h2.8l-6.9-8.3L20.5 4h-2.8l-4.6 5.6L8.8 4H4z']],
+    facebook: [
+        ['M14 4h-2.2A4.3 4.3 0 0 0 7.5 8.3V11H5v3h2.5v7h3.4v-7h2.6l.5-3h-3.1V8.6a1 1 0 0 1 1-1H14z'],
+    ],
+    instagram: [
+        // The square frame: outer body minus a smaller, concentric inner
+        // rectangle, one path so `evenodd` actually punches the hole.
+        [roundedRect(3, 3, 18, 18, 5), roundedRect(6, 6, 12, 12, 3.5)],
+        // The lens: outer minus inner circle, same technique.
+        [circlePath(12, 12, 4.2), circlePath(12, 12, 2.6)],
+        // The flash dot — solid, and deliberately its own group: joining it into
+        // either ring above would let `evenodd` cancel wherever it overlaps one.
+        [circlePath(17, 7, 1.3)],
+    ],
+    linkedin: [
+        [circlePath(6.5, 7, 1.6)],
+        [roundedRect(5.2, 10, 2.6, 10, 1)],
+        [
+            'M10.5 20V10h3v1.5c1-1.3 2.3-2 4-2c2.8 0 4.5 1.9 4.5 5V20h-3v-5c0-1.6-.7-2.6-2.2-2.6c-1.4 0-2.3 1-2.3 2.6V20z',
+        ],
+    ],
+    youtube: [
+        // The frame: outer minus inner rounded rect, same ring technique as
+        // instagram's own frame.
+        [roundedRect(2, 5, 20, 14, 5), roundedRect(4, 7, 16, 10, 3.5)],
+        // The play triangle — solid, its own group for the same reason as
+        // instagram's flash dot above.
+        ['M10 9l6 3-6 3z'],
+    ],
+    github: [
+        [circlePath(12, 11, 7)],
+        [
+            'M8.3 20v-2.1c-2-.5-3-1.4-3-3.3c0-1 .3-1.7 1-2.4c-.1-.5-.4-1.7.1-2.8c0 0 .9-.3 2.8 1a10 10 0 0 1 5.1 0c1.9-1.3 2.8-1 2.8-1c.5 1.1.2 2.3.1 2.8c.7.7 1 1.4 1 2.4c0 1.9-1 2.8-3 3.3V20',
+        ],
+    ],
+    mastodon: [['M4 8a4 4 0 0 1 4-4h8a4 4 0 0 1 4 4v4a4 4 0 0 1-4 4H10l-3 3v-3H8a4 4 0 0 1-4-4z']],
+    bluesky: [
+        [
+            'M12 9c-1.6-3-4.7-5-7-4c-1 3 .5 6.5 3.4 8c-2.9 1.5-4.4 5-3.4 8c2.3 1 5.4-1 7-4c1.6 3 4.7 5 7 4c1-3-.5-6.5-3.4-8c2.9-1.5 4.4-5 3.4-8c-2.3-1-5.4 1-7 4z',
+        ],
+    ],
+    tiktok: [
+        [circlePath(8, 17, 3)],
+        [roundedRect(9.4, 4, 2.4, 13, 1)],
+        ['M11.8 4c.3 3.2 2.7 5.4 5.7 5.6v3c-2.1-.1-4-.8-5.7-2.1'],
+    ],
+    // The loop: two overlapping, off-centre circles resolved into a crescent
+    // ring by `evenodd` — the whole reason this icon needs the technique at
+    // all, per this constant's own doc comment.
+    threads: [[circlePath(12, 12, 8), circlePath(13, 12, 4)]],
+    pinterest: [[roundedRect(10.4, 9, 2.4, 11, 1.2)], [circlePath(12.6, 10, 2.6)]],
+    // The generic fallback — two overlapping rounded-rectangle rings, the
+    // conventional "chain link" silhouette, each ring its own group (outer
+    // minus inner, resolved by `evenodd` within that one path) rather than
+    // four separate solid rectangles.
+    link: [
+        [roundedRect(1, 8, 12, 8, 4), roundedRect(3.5, 10.5, 7, 3, 1.5)],
+        [roundedRect(11, 8, 12, 8, 4), roundedRect(13.5, 10.5, 7, 3, 1.5)],
+    ],
+};
+/**
+ * `x.com`/`twitter.com`, Facebook, Instagram, LinkedIn, YouTube, GitHub,
+ * a Mastodon instance (any host whose path starts `/@`, since Mastodon is
+ * federated and has no one domain), Bluesky, TikTok, Threads, Pinterest — and
+ * `'link'` for anything else, including an unparseable URL.
+ */
+function socialIconKindFor(href) {
+    let url;
+    try {
+        url = new URL(href);
+    }
+    catch {
+        return 'link';
+    }
+    const host = url.hostname.toLowerCase().replace(/^www\./, '');
+    if (host === 'x.com' || host === 'twitter.com')
+        return 'x';
+    if (host === 'facebook.com' || host.endsWith('.facebook.com'))
+        return 'facebook';
+    if (host === 'instagram.com')
+        return 'instagram';
+    if (host === 'linkedin.com' || host.endsWith('.linkedin.com'))
+        return 'linkedin';
+    if (host === 'youtube.com' || host === 'youtu.be')
+        return 'youtube';
+    if (host === 'github.com')
+        return 'github';
+    if (host === 'bsky.app')
+        return 'bluesky';
+    if (host === 'tiktok.com' || host.endsWith('.tiktok.com'))
+        return 'tiktok';
+    if (host === 'threads.net')
+        return 'threads';
+    if (host === 'pinterest.com' || host.endsWith('.pinterest.com') || host === 'pinterest.fr') {
+        return 'pinterest';
+    }
+    if (url.pathname.startsWith('/@'))
+        return 'mastodon';
+    return 'link';
+}
+function socialIcon(kind, className) {
+    return h('svg', {
+        class: className,
+        viewBox: '0 0 24 24',
+        fill: 'currentColor',
+        'fill-rule': 'evenodd',
+        'aria-hidden': 'true',
+        focusable: 'false',
+    }, SOCIAL_ICON_PATHS[kind].map((group) => h('path', { d: group.join(' ') })));
+}
+/**
+ * `general.socialLinks` (contract D `theme@1.4`), as a `<ul>` of icon links —
+ * `null` when there is nothing to show, so a theme can write
+ * `renderSocialLinks(input.social)` straight into its footer without a
+ * conditional of its own.
+ *
+ * Every icon carries a visually-hidden text label (`cg-visually-hidden` — a
+ * theme that renders this must define that class, the standard
+ * clip-to-1px-and-hide technique, since `@cogenta/theme-kit` ships no CSS of
+ * its own) so the link's accessible name is still the platform *and* the
+ * label the site owner chose (`aria-label` would drop the wording an editor
+ * wrote; hidden text keeps it). `rel="me noopener noreferrer"` on every link:
+ * `me` is the [IndieWeb/Mastodon verification
+ * relation](https://indieweb.org/rel-me), harmless everywhere else, and the
+ * other two are the same external-link protection every theme already gives
+ * an off-site `<a>`.
+ */
+export function renderSocialLinks(social, options = {}) {
+    if (social === undefined || social.length === 0)
+        return null;
+    return h('ul', { class: options.className }, social.map((link) => h('li', { class: options.itemClassName }, h('a', { href: link.href, rel: 'me noopener noreferrer', target: '_blank' }, socialIcon(socialIconKindFor(link.href), 'cg-social__icon'), h('span', { class: 'cg-visually-hidden' }, link.label)))));
+}
+//# sourceMappingURL=chrome.js.map

package/dist/chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.js","sourceRoot":"","sources":["../src/chrome.ts"],"names":[],"mappings":"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"}

package/dist/comments.d.ts

@@ -0,0 +1,54 @@
+import { type HtmlElement } from './html.js';
+/**
+ * The comment thread and its submission form (fiche 15 task 6, ADR-0025).
+ *
+ * Contract B is frozen and a `comments` block would be a contract addition —
+ * this renders through the page template instead, called from the CLI's own
+ * render path (`packages/cli/src/commands/theme-render.ts`), appended after
+ * the page's own `<main>` rather than folded into it — never on the L16
+ * page-builder preview, deliberately: the form's own `_ts` anti-spam field is
+ * a render timestamp, legitimately different on every render, so it cannot
+ * be part of a fidelity claim that compares two separate renders byte for
+ * byte.
+ *
+ * Every piece of visitor-authored text — `authorName`, `body` — goes through
+ * this file's `h()`/`text()` tree, never a template string: there is no
+ * `raw()` escape hatch in `html.ts` (see its own module comment), which is
+ * what makes "no HTML submitted by a visitor ever reaches the rendered page"
+ * a structural property of this function rather than a habit to remember —
+ * and, since this module is shared, a property every theme package gets for
+ * free rather than one it has to reimplement correctly on its own.
+ */
+export interface PublicComment {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly authorName: string;
+    readonly authorUrl: string | null;
+    /** Plain text (R3) — rendered as-is inside a `<p>`, never interpreted as markup. */
+    readonly body: string;
+    readonly createdAt: string;
+}
+export interface CommentsSectionOptions {
+    readonly comments: readonly PublicComment[];
+    /** Whether this entry currently accepts new comments (settings inheritance already resolved by the caller). */
+    readonly open: boolean;
+    /** `POST` target — `/api/comments` in every real deployment, parameterised so a test can point elsewhere. */
+    readonly action: string;
+    readonly collection: string;
+    readonly entryId: string;
+    readonly locale: string | null;
+    /** The page's own path, echoed back as `redirectTo` so a no-JS submission returns here (`CommentsRouter`'s 303 branch) instead of showing raw JSON. */
+    readonly pagePath: string;
+    /** The hidden field a bot fills and a human never sees. Must match the router's own `honeypotField` (defaults to `website` on both sides). */
+    readonly honeypotField?: string;
+    /** Server time this page was rendered, ms since epoch — the minimum-fill-delay hidden field. */
+    readonly renderedAt: number;
+}
+/**
+ * The whole section: heading, thread, and — only when `open` — the form.
+ * Returned as an `HtmlElement`, appended by the caller after the page's own
+ * `<main>`, never inside it — a comment thread is not page content, it is a
+ * property of the route the same way `/search`'s results are.
+ */
+export declare function renderCommentsSection(options: CommentsSectionOptions): HtmlElement;
+//# sourceMappingURL=comments.d.ts.map

package/dist/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,WAAW,EAAW,MAAM,WAAW,CAAA;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAC3C,+GAA+G;IAC/G,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uJAAuJ;IACvJ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,8IAA8I;IAC9I,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AA2HD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,WAAW,CAclF"}

package/dist/comments.js

@@ -0,0 +1,68 @@
+import { h, text } from './html.js';
+function buildTree(comments) {
+    const byParent = new Map();
+    for (const comment of comments) {
+        const bucket = byParent.get(comment.parentId) ?? [];
+        bucket.push(comment);
+        byParent.set(comment.parentId, bucket);
+    }
+    function attach(parentId) {
+        return (byParent.get(parentId) ?? []).map((comment) => ({
+            ...comment,
+            replies: attach(comment.id),
+        }));
+    }
+    return attach(null);
+}
+function renderComment(node) {
+    return h('li', { class: 'cg-comment', id: `comment-${node.id}` }, h('article', {}, h('header', { class: 'cg-comment__meta' }, h('span', { class: 'cg-comment__author' }, text(node.authorName)), h('time', { class: 'cg-comment__date', datetime: node.createdAt }, text(new Date(node.createdAt).toLocaleDateString()))), h('p', { class: 'cg-comment__body' }, text(node.body))), node.replies.length === 0
+        ? null
+        : h('ol', { class: 'cg-comment__replies' }, node.replies.map(renderComment)));
+}
+function hidden(name, value) {
+    return h('input', { type: 'hidden', name, value });
+}
+/** The submission form — a plain HTML `<form method="post">`, no JavaScript required (fiche 15 task 6). */
+function renderForm(options, parentId) {
+    const honeypot = options.honeypotField ?? 'website';
+    const formId = parentId === undefined ? 'cg-comment-form' : `cg-comment-form-${parentId}`;
+    return h('form', {
+        id: formId,
+        class: 'cg-comment__form',
+        method: 'post',
+        action: options.action,
+    }, hidden('collection', options.collection), hidden('entryId', options.entryId), ...(options.locale === null ? [] : [hidden('locale', options.locale)]), ...(parentId === undefined ? [] : [hidden('parentId', parentId)]), hidden('redirectTo', options.pagePath), hidden('_ts', String(options.renderedAt)), 
+    // The honeypot: a real visitor never sees or fills this in. Hidden by an
+    // attribute a theme's own stylesheet never has to know about — the
+    // element is not `type="hidden"` on purpose, so a bot's naive "fill
+    // every input" script still finds and fills it.
+    h('div', { class: 'cg-comment__honeypot', 'aria-hidden': 'true' }, h('label', { for: `${formId}-hp` }, text('Leave this field empty')), h('input', {
+        id: `${formId}-hp`,
+        type: 'text',
+        name: honeypot,
+        tabindex: -1,
+        autocomplete: 'off',
+    })), h('p', {}, h('label', { for: `${formId}-name` }, text('Name')), h('input', {
+        id: `${formId}-name`,
+        type: 'text',
+        name: 'name',
+        required: true,
+        maxlength: 200,
+    })), h('p', {}, h('label', { for: `${formId}-email` }, text('E-mail (not published)')), h('input', { id: `${formId}-email`, type: 'email', name: 'email', required: true })), h('p', {}, h('label', { for: `${formId}-url` }, text('Website (optional)')), h('input', { id: `${formId}-url`, type: 'url', name: 'authorUrl' })), h('p', {}, h('label', { for: `${formId}-body` }, text(parentId === undefined ? 'Comment' : 'Reply')), h('textarea', { id: `${formId}-body`, name: 'body', required: true, rows: 5 })), h('p', {}, h('button', { type: 'submit' }, text(parentId === undefined ? 'Post comment' : 'Post reply'))));
+}
+/**
+ * The whole section: heading, thread, and — only when `open` — the form.
+ * Returned as an `HtmlElement`, appended by the caller after the page's own
+ * `<main>`, never inside it — a comment thread is not page content, it is a
+ * property of the route the same way `/search`'s results are.
+ */
+export function renderCommentsSection(options) {
+    const tree = buildTree(options.comments);
+    const headingAttrs = { id: 'cg-comments-heading' };
+    return h('section', { class: 'cg-comments', 'aria-labelledby': 'cg-comments-heading' }, h('h2', headingAttrs, text(`Comments (${options.comments.length})`)), tree.length === 0
+        ? h('p', { class: 'cg-comments__empty' }, text('No comments yet.'))
+        : h('ol', { class: 'cg-comments__list' }, tree.map(renderComment)), options.open
+        ? renderForm(options)
+        : h('p', { class: 'cg-comments__closed' }, text('Comments are closed on this page.')));
+}
+//# sourceMappingURL=comments.js.map

package/dist/comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,CAAC,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAsDtE,SAAS,SAAS,CAAC,QAAkC;IACnD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAA;IAC1D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAA;QACnD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACpB,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACxC,CAAC;IACD,SAAS,MAAM,CAAC,QAAuB;QACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACtD,GAAG,OAAO;YACV,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;SAC5B,CAAC,CAAC,CAAA;IACL,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;AACrB,CAAC;AAED,SAAS,aAAa,CAAC,IAAiB;IACtC,OAAO,CAAC,CACN,IAAI,EACJ,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,WAAW,IAAI,CAAC,EAAE,EAAE,EAAE,EACjD,CAAC,CACC,SAAS,EACT,EAAE,EACF,CAAC,CACC,QAAQ,EACR,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAC7B,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EACjE,CAAC,CACC,MAAM,EACN,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,EACvD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,kBAAkB,EAAE,CAAC,CACpD,CACF,EACD,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CACvD,EACD,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAC/E,CAAA;AACH,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,KAAa;IACzC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;AACpD,CAAC;AAED,2GAA2G;AAC3G,SAAS,UAAU,CAAC,OAA+B,EAAE,QAAiB;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI,SAAS,CAAA;IACnD,MAAM,MAAM,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,QAAQ,EAAE,CAAA;IACzF,OAAO,CAAC,CACN,MAAM,EACN;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,kBAAkB;QACzB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,EACD,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,EACxC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,EAClC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EACtE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjE,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,EACtC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACzC,yEAAyE;IACzE,mEAAmE;IACnE,oEAAoE;IACpE,gDAAgD;IAChD,CAAC,CACC,KAAK,EACL,EAAE,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAA4B,EAAE,EAC9E,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,KAAK,EAAE,EAAE,IAAI,CAAC,wBAAwB,CAAC,CAAC,EACnE,CAAC,CAAC,OAAO,EAAE;QACT,EAAE,EAAE,GAAG,MAAM,KAAK;QAClB,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,CAAC;QACZ,YAAY,EAAE,KAAK;KACpB,CAAC,CACH,EACD,CAAC,CACC,GAAG,EACH,EAAE,EACF,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,OAAO,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,EACnD,CAAC,CAAC,OAAO,EAAE;QACT,EAAE,EAAE,GAAG,MAAM,OAAO;QACpB,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,GAAG;KACf,CAAC,CACH,EACD,CAAC,CACC,GAAG,EACH,EAAE,EACF,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,QAAQ,EAAE,EAAE,IAAI,CAAC,wBAAwB,CAAC,CAAC,EACtE,CAAC,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CACpF,EACD,CAAC,CACC,GAAG,EACH,EAAE,EACF,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,EAAE,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC,EAChE,CAAC,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CACpE,EACD,CAAC,CACC,GAAG,EACH,EAAE,EACF,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,OAAO,EAAE,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EACzF,CAAC,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAC/E,EACD,CAAC,CACC,GAAG,EACH,EAAE,EACF,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAC9F,CACF,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxC,MAAM,YAAY,GAAe,EAAE,EAAE,EAAE,qBAAqB,EAAE,CAAA;IAC9D,OAAO,CAAC,CACN,SAAS,EACT,EAAE,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,EAClE,CAAC,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,aAAa,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,EACpE,IAAI,CAAC,MAAM,KAAK,CAAC;QACf,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,EACpE,OAAO,CAAC,IAAI;QACV,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;QACrB,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,IAAI,CAAC,mCAAmC,CAAC,CAAC,CACxF,CAAA;AACH,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Contract D, transcribed once for every theme package to implement against.
+ *
+ * `ThemeManifest`/`defineTheme`/`SkinTokens` are `@cogenta/render`'s own,
+ * already-validated definitions (`theme/manifest.ts`, `skin/tokens.ts`) —
+ * re-exported here rather than duplicated, since `@cogenta/render` is also
+ * what `loadTheme`/`verifyTheme`/the plugin theme marketplace already check
+ * a manifest against. A second, drifting copy of either is exactly the
+ * mistake this package exists to stop repeating.
+ *
+ * `RenderContext`/`ContentEntry`/`ContentClient`/`QueryRequest`/`Page` below
+ * are declared fresh here rather than imported from `@cogenta/render`: that
+ * package's own `context/types.ts` shapes a *different*, still-unused
+ * pipeline (the deferred Astro static build, `astro/integration.ts`) whose
+ * `ContentEntry` nests fields under `.values` and whose `MediaReference` is a
+ * full asset object — incompatible with the flat, string-keyed contract
+ * `cogenta serve`'s real, tested SSR path has used since L3 and every theme
+ * (including this repository's own reference theme) is built against.
+ * Unifying onto the Astro shape would change live, working behaviour for a
+ * pipeline nothing serves through yet — this contract is the one actually in
+ * production, transcribed rather than guessed at.
+ *
+ * `ImageOptions`/`ImageSource` *are* taken from `@cogenta/render` — those two
+ * are genuinely the same contract on both pipelines (`describeMedia`, which
+ * `cogenta serve` already calls, returns exactly this shape), and reusing
+ * them picks up `kind`/`poster` (`theme@1.1`): the fix that lets a theme tell
+ * a video apart from a broken image, which the very first theme built against
+ * the pre-1.1 copy of this contract could not.
+ */
+import type { ImageOptions, ImageSource } from '@cogenta/render';
+export type { ImageOptions, ImageSource, SkinTokens, ThemeManifest, ThemeRuntime, } from '@cogenta/render';
+export { defineTheme } from '@cogenta/render';
+/**
+ * Contract B stores a media field as the media library's identifier, never as
+ * an URL and never as a rendition (`f.media` in `@cogenta/blocks`). So a
+ * reference a theme holds is that identifier.
+ */
+export type MediaReference = string;
+/**
+ * Contract A fixes the system fields but not the schema-defined ones — a
+ * theme only ever sees published entries (the read token carries the
+ * `public` role), so `status` is narrow in practice but kept whole here
+ * rather than guessed at.
+ */
+export interface ContentEntry {
+    readonly id: string;
+    readonly collection: string;
+    readonly locale: string;
+    readonly status: 'draft' | 'scheduled' | 'published' | 'archived';
+    readonly [field: string]: unknown;
+}
+export interface QueryRequest {
+    readonly collection: string;
+    readonly filter?: Readonly<Record<string, unknown>>;
+    readonly sort?: {
+        readonly field: string;
+        readonly direction: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+export interface Page<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+}
+export interface ContentClient {
+    entry(collection: string, id: string): Promise<ContentEntry | null>;
+    byPath(path: string): Promise<ContentEntry | null>;
+    list(request: QueryRequest): Promise<Page<ContentEntry>>;
+}
+export type LinkTargetInput = {
+    collection: string;
+    id: string;
+} | {
+    path: string;
+} | string;
+export interface RenderContext {
+    readonly site: {
+        readonly name: string;
+        readonly url: string;
+        readonly locales: readonly string[];
+        readonly defaultLocale: string;
+    };
+    /** The locale being rendered. */
+    readonly locale: string;
+    /** The URL being rendered, already resolved. */
+    readonly url: URL;
+    /** Translation. An unknown key returns the key, never an empty string. */
+    t(key: string, values?: Readonly<Record<string, string | number>>): string;
+    /** Image variants. Returns what a responsive `<img>` (or `<video>`) needs, nothing more. */
+    image(media: MediaReference, options?: ImageOptions): ImageSource;
+    /** URL of an entry, of a path, or of an external target. Locale-aware. */
+    link(target: LinkTargetInput): string;
+    /** Read-only content access. The only door to data a theme has. */
+    readonly content: ContentClient;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAEhE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAE7C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAA;IACjE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAA;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IACnE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IAClD,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAA;CACzD;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAA;AAE5F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;QACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IAEjB,0EAA0E;IAC1E,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,MAAM,CAAA;IAE1E,4FAA4F;IAC5F,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAAA;IAEjE,0EAA0E;IAC1E,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAA;IAErC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAChC"}