@caltho/site-kit 0.2.2 → 0.2.4

package/README.md

@@ -66,6 +66,31 @@ the kit only checks it's a URL.
 | **Preview** (`@caltho/site-kit/next/preview`) | `SitePreview`: CalOS's draft drawn with the site's own components, a click matched to its field, outlines with each section's name. |
 | **Schema** (`@caltho/site-kit/schema`) | What CalOS needs of a declaration with no site code: validate content against the JSON Schema with messages a person can act on, make a blank block or entry, list the kinds of block, and the checks across pages. |
 
+## Share cards
+
+Each page is shared (Open Graph) with a 1200×630 card made at build from its words: its title and
+description, or the **Share title** and **Share text** an owner can set in CalOS's page settings, with
+the business's name. Every publish rebuilds the site, so a card always says what the page says. A
+**Share picture** chosen for a page is used instead.
+
+A site sets how its cards look in `content/schema.ts`:
+
+```ts
+export default defineSite(blocks, {
+  share: {
+    background: "#13262f", color: "#ffffff", muted: "#b8c7cf", accent: "#f2b134",
+    backgroundImage: "public/og.png",       // drawn behind, stretched to 1200×630
+    logo: "public/logo.svg",                // instead of the business's name in words
+    fonts: [{ name: "Brand Sans", path: "assets/fonts/BrandSans-Bold.woff", weight: 700 }],
+    prefer: "picture",                      // a page's first picture before its card
+    render: (card, h) => h.el({ width: "100%", height: "100%", padding: 72 }, card.title), // a card of its own
+  },
+});
+```
+
+`share: false` turns cards off: pages are shared with a picture from them. The kit carries DM Sans (SIL
+Open Font License, `src/fonts/OFL.txt`) for cards that don't name fonts of their own.
+
 ## A build
 
 ```sh

package/dist/content/index.d.ts

@@ -1,3 +1,5 @@
+import type { ShareOptions } from "../share.ts";
+export type { CardNode, ShareCard, ShareFont, ShareOptions } from "../share.ts";
 import { z } from "zod";
 export { checkStructure, describePath, type StructureIssue } from "../schema.ts";
 export { z };
@@ -87,6 +89,8 @@ export type Page = {
         src: string;
         alt: string;
     };
+    shareTitle?: string;
+    shareText?: string;
     noindex: boolean;
     blocks: Block[];
 };
@@ -99,14 +103,52 @@ export type Redirect = {
     status: 301 | 302;
 };
 /** What every site has, whatever its blocks. */
+export type MenuLink = {
+    label: string;
+    href: string;
+    emphasis?: boolean;
+};
+export type Menu = {
+    links: MenuLink[];
+    button?: {
+        label: string;
+        href: string;
+    };
+};
+export type FooterLink = {
+    label: string;
+    href: string;
+};
+export type Footer = {
+    columns: {
+        heading?: string;
+        links: FooterLink[];
+    }[];
+    legal: FooterLink[];
+    note?: string;
+};
 export type SiteBase = {
     url: string;
     lang: string;
     business: Business;
     form?: string;
+    menu?: Menu;
+    footer?: Footer;
     redirects: Redirect[]; /** Whether page paths end in a slash (the default). */
     trailingSlash?: boolean;
 };
+/**
+ * The site's menu, as its header draws it: the one edited in CalOS (its links in order, one picked out,
+ * and the header's button), else the pages that have a menu label, in page order (and no button: the
+ * site's own default).
+ */
+export declare function menuOf(site: Pick<Site, "pages" | "menu">): Menu;
+/**
+ * The site's footer links, as its footer draws them: the ones edited in CalOS (columns, each with
+ * its heading; the legal row; a line of small print), else one column of the menu's links and no
+ * legal row (the site's own default, its policy pages say).
+ */
+export declare function footerOf(site: Pick<Site, "pages" | "menu" | "footer">): Footer;
 /** The content as the kit sees it: what search, security, images and the checks need. A site's own type has its blocks and extra fields. */
 export type Site = SiteBase & {
     pages: Page[];
@@ -136,6 +178,8 @@ export type DefineOptions = {
     extend?: z.ZodRawShape;
     /** Checks only the site can make (a contact block needs somewhere to send), added to the kit's own. */
     refine?: (site: Site, ctx: z.RefinementCtx) => void;
+    /** How each page's share card looks (colours, fonts, a logo, or a card of the site's own); `false` for none (../share.ts). */
+    share?: ShareOptions;
 };
 /**
  * A site's content shape from its blocks: each a name and the fields it has. The site's own block
@@ -153,6 +197,8 @@ export declare function defineSite<const B extends Record<string, z.ZodObject>>(
                 src: z.ZodString;
                 alt: z.ZodString;
             }, z.core.$strip>>;
+            shareTitle: z.ZodOptional<z.ZodString>;
+            shareText: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
         url: z.ZodURL;
@@ -205,6 +251,31 @@ export declare function defineSite<const B extends Record<string, z.ZodObject>>(
             }, z.core.$strip>>;
         }, z.core.$strip>;
         form: z.ZodOptional<z.ZodURL>;
+        menu: z.ZodOptional<z.ZodObject<{
+            links: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                href: z.ZodString;
+                emphasis: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            button: z.ZodOptional<z.ZodObject<{
+                label: z.ZodString;
+                href: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        footer: z.ZodOptional<z.ZodObject<{
+            columns: z.ZodArray<z.ZodObject<{
+                heading: z.ZodOptional<z.ZodString>;
+                links: z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    href: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            legal: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                href: z.ZodString;
+            }, z.core.$strip>>>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
         redirects: z.ZodDefault<z.ZodArray<z.ZodObject<{
             from: z.ZodString;
             to: z.ZodString;
@@ -224,6 +295,8 @@ export declare function defineSite<const B extends Record<string, z.ZodObject>>(
                     src: z.ZodString;
                     alt: z.ZodString;
                 }, z.core.$strip>>;
+                shareTitle: z.ZodOptional<z.ZodString>;
+                shareText: z.ZodOptional<z.ZodString>;
                 noindex: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
             url: z.ZodURL;
@@ -276,6 +349,31 @@ export declare function defineSite<const B extends Record<string, z.ZodObject>>(
                 }, z.core.$strip>>;
             }, z.core.$strip>;
             form: z.ZodOptional<z.ZodURL>;
+            menu: z.ZodOptional<z.ZodObject<{
+                links: z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    href: z.ZodString;
+                    emphasis: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>;
+                button: z.ZodOptional<z.ZodObject<{
+                    label: z.ZodString;
+                    href: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            footer: z.ZodOptional<z.ZodObject<{
+                columns: z.ZodArray<z.ZodObject<{
+                    heading: z.ZodOptional<z.ZodString>;
+                    links: z.ZodArray<z.ZodObject<{
+                        label: z.ZodString;
+                        href: z.ZodString;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
+                legal: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    href: z.ZodString;
+                }, z.core.$strip>>>;
+                note: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
             redirects: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 from: z.ZodString;
                 to: z.ZodString;
@@ -293,6 +391,7 @@ export declare function defineSite<const B extends Record<string, z.ZodObject>>(
     };
     trailingSlash: boolean;
     csp: Record<string, string[]>;
+    share: ShareOptions | undefined;
     /** The declaration CalOS draws its editing forms from. */
     jsonSchema: () => Record<string, unknown>;
 };

package/dist/content/index.js

@@ -77,10 +77,29 @@ const pageBase = (trailingSlash) => ({
     description: text,
     /** Its label in the menu; leave out to keep it off the menu. */
     menu: text.optional(),
-    /** The picture shown when the page is shared; defaults to the first image on it. */
-    share: image.optional(),
+    /** A picture to share the page with instead of its card (made from its words at build). */
+    share: image.optional().meta({ title: "Share picture" }),
+    /** What the page's share card says, when not its title and description. */
+    shareTitle: text.optional().meta({ title: "Share title" }),
+    shareText: longText.optional().meta({ title: "Share text" }),
     noindex: z.boolean().default(false),
 });
+/**
+ * The site's menu, as its header draws it: the one edited in CalOS (its links in order, one picked out,
+ * and the header's button), else the pages that have a menu label, in page order (and no button: the
+ * site's own default).
+ */
+export function menuOf(site) {
+    return site.menu ?? { links: site.pages.filter((p) => p.menu).map((p) => ({ label: p.menu, href: p.path })) };
+}
+/**
+ * The site's footer links, as its footer draws them: the ones edited in CalOS (columns, each with
+ * its heading; the legal row; a line of small print), else one column of the menu's links and no
+ * legal row (the site's own default, its policy pages say).
+ */
+export function footerOf(site) {
+    return site.footer ?? { columns: [{ links: menuOf(site).links.map(({ label, href }) => ({ label, href })) }], legal: [] };
+}
 /**
  * A site's content shape from its blocks: each a name and the fields it has. The site's own block
  * type is `z.output<typeof content.schema>["pages"][number]["blocks"][number]`.
@@ -106,6 +125,23 @@ export function defineSite(blocks, o = {}) {
         business,
         /** Where the contact forms post to, if the site has any (a CalOS form's address, or another service's). */
         form: z.url({ protocol: /^https?$/ }).meta({ title: "Where its forms send" }).optional(),
+        /** The header's links in order, and its button: edited as one list in CalOS. Left out, the pages' menu labels are used. */
+        menu: z
+            .object({
+            links: z.array(z.object({ label: text, href, emphasis: z.boolean().default(false).meta({ title: "Emphasize" }) })).max(10),
+            button: z.object({ label: text, href }).optional().meta({ title: "Button" }),
+        })
+            .optional()
+            .meta({ title: "Menu" }),
+        /** The footer's links: columns, the legal row, and a line of small print. Left out, the menu's links are used. */
+        footer: z
+            .object({
+            columns: z.array(z.object({ heading: text.optional(), links: z.array(z.object({ label: text, href })).max(12) })).max(4),
+            legal: z.array(z.object({ label: text, href })).max(6).default([]).meta({ title: "Legal links" }),
+            note: text.optional().meta({ title: "Small print" }),
+        })
+            .optional()
+            .meta({ title: "Footer" }),
         /** Old addresses kept answering, when CalOS doesn't supply them at build. */
         redirects: z.array(z.object({ from: z.string().startsWith("/"), to: href, status: z.union([z.literal(301), z.literal(302)]).default(301) })).default([]),
         ...o.extend,
@@ -128,6 +164,7 @@ export function defineSite(blocks, o = {}) {
         },
         trailingSlash,
         csp: o.csp ?? {},
+        share: o.share,
         /** The declaration CalOS draws its editing forms from. */
         jsonSchema: () => z.toJSONSchema(schema, { io: "input", unrepresentable: "any" }),
     };

package/dist/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) and the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/next/metadata.js

@@ -2,13 +2,18 @@
 // all from the prepared content.
 import { shareImageOf } from "../images.js";
 import { canonical, fullTitle } from "../seo.js";
-import { image, site } from "./data.js";
+import { image, prepared, site } from "./data.js";
 export function pageMetadata(page) {
     const s = site();
     const title = fullTitle(s, page);
     const url = canonical(s, page.path);
-    const share = shareImageOf(s, page);
-    const shareUrl = share ? image(share.src).share : undefined;
+    // Shared with: the picture chosen for it, else its card (else, with cards off or a site that
+    // prefers them, its first picture).
+    const p = prepared();
+    const card = p.cards?.[page.path];
+    const picture = page.share ?? (!card || p.preferPicture ? shareImageOf(s, page) : undefined);
+    const share = picture && !picture.src.endsWith(".svg") ? picture : undefined;
+    const shareUrl = share ? image(share.src).share : card;
     return {
         metadataBase: new URL(s.url),
         title: { absolute: title },
@@ -22,7 +27,7 @@ export function pageMetadata(page) {
             description: page.description,
             url,
             locale: s.lang.replace("-", "_"),
-            images: shareUrl && share ? [{ url: new URL(shareUrl, s.url).href, width: 1200, height: 630, alt: share.alt }] : undefined,
+            images: shareUrl ? [{ url: new URL(shareUrl, s.url).href, width: 1200, height: 630, alt: share?.alt ?? page.title }] : undefined,
         },
         twitter: { card: shareUrl ? "summary_large_image" : "summary" },
     };

package/dist/next/preview.js

@@ -119,6 +119,10 @@ export function SitePreview({ origins, render }) {
         hovered = null;
         outline("section", null);
         outline("hover", null);
+        // Another page starts at its top, unless a section on it is to be brought into view.
+        if (shown.path !== drawnPath && !(el && shown.scroll))
+            window.scrollTo({ top: 0 });
+        drawnPath = shown.path;
         // Scrolled here only: scrollIntoView would scroll CalOS's page around the frame too.
         if (el && shown.scroll)
             window.scrollTo({ top: el.getBoundingClientRect().top + window.scrollY - window.innerHeight / 4, behavior: "smooth" });
@@ -265,6 +269,8 @@ const looks = {
     hover: { outline: `1px dashed ${BLUE}`, outlineOffset: "3px", borderRadius: "3px" },
 };
 let hovered = null;
+/** The page last drawn, so another one starts at its top. */
+let drawnPath = null;
 const boxes = {};
 function outline(which, el, label) {
     let made = boxes[which];

package/dist/prepare.d.ts

@@ -21,6 +21,10 @@ export type Prepared = {
     csp: Record<string, string[]>;
     /** The addresses of the CalOS this content came from (every one the business uses it on): those that may draw drafts in the preview. */
     editors?: string[];
+    /** Each page's share card (../share.ts), by its path; none when the site turned them off. */
+    cards?: Record<string, string>;
+    /** Whether a page with pictures but no share picture chosen is shared with its first picture rather than its card. */
+    preferPicture?: boolean;
 };
 type Log = (line: string) => void;
 export declare function prepare(root: string, env?: Record<string, string | undefined>, log?: Log): Promise<Prepared>;

package/dist/prepare.js

@@ -20,6 +20,7 @@ import { dirname, extname, join, relative } from "node:path";
 import sharp from "sharp";
 import { pathToFileURL } from "node:url";
 import { imagesIn, shareImageOf } from "./images.js";
+import { makeCards } from "./share.js";
 const WIDTHS = [400, 640, 800, 1024, 1280, 1600, 2000];
 export async function prepare(root, env = process.env, log = console.log) {
     const out = join(root, ".site");
@@ -86,7 +87,9 @@ export async function prepare(root, env = process.env, log = console.log) {
     if (env.CALOS_CONTENT_URL)
         await pushSchema(env.CALOS_CONTENT_URL, env.CALOS_SCHEMA_URL, env.CALOS_SITE_TOKEN, schema, log);
     const images = await pictures(site, imagesDir, pub, log);
-    const prepared = { site, images, csp: definition.csp, ...(editors.length ? { editors } : {}) };
+    const cards = await makeCards(site, definition.share, root, pub, log);
+    const preferPicture = !!definition.share && definition.share.prefer === "picture";
+    const prepared = { site, images, csp: definition.csp, cards, ...(preferPicture ? { preferPicture } : {}), ...(editors.length ? { editors } : {}) };
     await writeFile(join(out, "prepared.json"), JSON.stringify(prepared));
     log(`site-kit: content from ${from}, ${site.pages.length} pages, ${Object.keys(images).length} images`);
     return prepared;

package/dist/share.d.ts

@@ -0,0 +1,54 @@
+import type { Page, Site } from "./content/index.ts";
+export declare const SHARE_WIDTH = 1200;
+export declare const SHARE_HEIGHT = 630;
+/** What a card says. */
+export type ShareCard = {
+    title: string;
+    text: string;
+    business: string;
+    path: string;
+};
+/** A node of the card, as satori draws it (a subset of HTML and CSS, flexbox only). */
+export type CardNode = {
+    type: string;
+    props: Record<string, unknown> & {
+        style?: Record<string, unknown>;
+        children?: unknown;
+    };
+};
+export type ShareFont = {
+    name: string; /** A .woff, .ttf or .otf, from the site's root. */
+    path: string;
+    weight?: 400 | 500 | 600 | 700;
+    style?: "normal" | "italic";
+};
+export type ShareOptions = false | {
+    /** The card's colour behind everything (any CSS colour). */
+    background?: string;
+    /** A picture behind it, from the site's root (public/og.png), stretched to 1200×630. */
+    backgroundImage?: string;
+    /** The title's colour, the text's, and the line above the title. */
+    color?: string;
+    muted?: string;
+    accent?: string;
+    /** The business's logo (a .png or .svg from the site's root), top left; else its name in words. */
+    logo?: string;
+    /** The site's own fonts; the first's name is the family used. Else DM Sans, which the kit carries. */
+    fonts?: ShareFont[];
+    /** Which first, for a page that has pictures but no share picture chosen: the card (the default) or its first picture. */
+    prefer?: "card" | "picture";
+    /** A card of the site's own: given what it says and helpers, the node to draw. */
+    render?: (card: ShareCard, h: {
+        el: typeof el;
+        image: (path: string) => Promise<string>;
+    }) => CardNode | Promise<CardNode>;
+};
+/** A box: a div, flex by default as satori wants it. */
+export declare const el: (style: Record<string, unknown>, children?: unknown, props?: Record<string, unknown>) => CardNode;
+/** What a page's card says: the share title and text CalOS can set, else its title and description. */
+export declare function cardOf(site: Site, page: Page): ShareCard;
+/**
+ * Each page's card, made into public/_img/share/ (named from what it says and how it's drawn, so a
+ * card already made is kept); its address by page path. Nothing when the site turned cards off.
+ */
+export declare function makeCards(site: Site, options: ShareOptions | undefined, root: string, pub: string, log?: (line: string) => void): Promise<Record<string, string>>;

package/dist/share.js

@@ -0,0 +1,87 @@
+// The card each page is shared with (Open Graph, 1200×630): made at build from the page's own words
+// (its share title and text when CalOS gives it them, else its title and description) and the
+// business's name, in the site's colours and fonts. Content edited in CalOS rebuilds the site, so a
+// card always says what the page says. A page with a share picture chosen keeps the picture.
+//
+// A site sets how its cards look with `defineSite(blocks, { share })`: colours, a background picture,
+// fonts, a logo, or its own `render` for a different card altogether; `share: false` turns cards
+// off (pages are shared with a picture from them, as before).
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { Resvg } from "@resvg/resvg-js";
+import satori from "satori";
+export const SHARE_WIDTH = 1200;
+export const SHARE_HEIGHT = 630;
+/** A box: a div, flex by default as satori wants it. */
+export const el = (style, children, props = {}) => ({ type: "div", props: { ...props, style: { display: "flex", ...style }, children } });
+/** What a page's card says: the share title and text CalOS can set, else its title and description. */
+export function cardOf(site, page) {
+    const p = page;
+    return { title: (p.shareTitle ?? page.title).slice(0, 120), text: (p.shareText ?? page.description).slice(0, 180), business: site.business.name, path: page.path };
+}
+const KIT_FONTS = [
+    { name: "DM Sans", path: "DMSans-Regular.woff", weight: 400 },
+    { name: "DM Sans", path: "DMSans-Medium.woff", weight: 500 },
+    { name: "DM Sans", path: "DMSans-Bold.woff", weight: 700 },
+];
+const TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".svg": "image/svg+xml" };
+async function dataUri(root, path) {
+    const type = TYPES[extname(path).toLowerCase()];
+    if (!type)
+        throw new Error(`The share card's picture ${path} isn't a .png, .jpg, .webp or .svg`);
+    return `data:${type};base64,${(await readFile(join(root, path))).toString("base64")}`;
+}
+/** The card the kit draws when a site doesn't draw its own: its name (or logo), the title large, the text under it. */
+async function defaultCard(card, o, root, family) {
+    const size = card.title.length > 60 ? 54 : card.title.length > 32 ? 66 : 80;
+    const bg = o.backgroundImage ? { backgroundImage: `url(${await dataUri(root, o.backgroundImage)})`, backgroundSize: "100% 100%" } : {};
+    const top = o.logo
+        ? { type: "img", props: { src: await dataUri(root, o.logo), height: 56, style: { height: 56, objectFit: "contain" } } }
+        : el({ fontSize: 30, fontWeight: 700, color: o.color ?? "#16181d", letterSpacing: "-0.02em" }, card.business);
+    return el({ width: "100%", height: "100%", flexDirection: "column", justifyContent: "space-between", padding: "72px", background: o.background ?? "#f7f6f2", fontFamily: family, ...bg }, [
+        top,
+        el({ flexDirection: "column", gap: "24px", maxWidth: "980px" }, [
+            el({ width: 72, height: 6, borderRadius: 3, background: o.accent ?? "#2b5f8a" }),
+            el({ fontSize: size, fontWeight: 700, lineHeight: 1.08, letterSpacing: "-0.03em", color: o.color ?? "#16181d" }, card.title),
+            ...(card.text ? [el({ fontSize: 30, fontWeight: 400, lineHeight: 1.4, color: o.muted ?? "#575c66", maxWidth: "900px" }, card.text)] : []),
+        ]),
+    ]);
+}
+/**
+ * Each page's card, made into public/_img/share/ (named from what it says and how it's drawn, so a
+ * card already made is kept); its address by page path. Nothing when the site turned cards off.
+ */
+export async function makeCards(site, options, root, pub, log = () => { }) {
+    if (options === false)
+        return {};
+    const o = options ?? {};
+    const fonts = o.fonts?.length ? o.fonts.map((f) => ({ ...f, from: root })) : KIT_FONTS.map((f) => ({ ...f, from: new URL("./fonts/", import.meta.url).pathname }));
+    const loaded = await Promise.all(fonts.map(async (f) => ({ name: f.name, data: await readFile(join(f.from, f.path)), weight: f.weight ?? 400, style: f.style ?? "normal" })));
+    const family = fonts[0].name;
+    const dir = join(pub, "_img", "share");
+    await mkdir(dir, { recursive: true });
+    // How the cards are drawn, in the names: a change of colours, fonts or the site's own render makes them anew.
+    const look = createHash("sha256")
+        .update(JSON.stringify({ ...o, render: o.render?.toString() ?? null }))
+        .digest("hex");
+    const out = {};
+    let made = 0;
+    for (const page of site.pages) {
+        const card = cardOf(site, page);
+        const hash = createHash("sha256").update(look).update(JSON.stringify(card)).digest("hex").slice(0, 10);
+        const slug = page.path.replace(/^\/|\/$/g, "").replace(/[^\w-]+/g, "-") || "home";
+        const name = `${slug}.${hash}.png`;
+        out[page.path] = `/_img/share/${name}`;
+        if (existsSync(join(dir, name)))
+            continue;
+        const node = o.render ? await o.render(card, { el, image: (path) => dataUri(root, path) }) : await defaultCard(card, o, root, family);
+        const svg = await satori(node, { width: SHARE_WIDTH, height: SHARE_HEIGHT, fonts: loaded });
+        await writeFile(join(dir, name), new Resvg(svg, { fitTo: { mode: "width", value: SHARE_WIDTH } }).render().asPng());
+        made++;
+    }
+    if (made)
+        log(`site-kit: ${made} share card${made === 1 ? "" : "s"} made`);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caltho/site-kit",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "What every Caltho site is built with: the contract with CalOS (content, and how a site declares what is editable), images, search and security, and the checks",
   "license": "MIT",
   "type": "module",
@@ -50,13 +50,15 @@
     "node": ">=22.18"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli/index.js",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/fonts dist/fonts && chmod +x dist/cli/index.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test src",
     "prepack": "bun run build"
   },
   "dependencies": {
+    "@resvg/resvg-js": "2.6.2",
     "marked": "18.1.0",
+    "satori": "0.33.4",
     "sharp": "0.35.5",
     "zod": "4.6.7"
   },