astro-cards 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Bouqdib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,231 @@
-# astro-cards
+# astro-cards 🏞️
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+An Astro integration that renders `.astro` components to images. Open Graph cards, badges, tickets,
+or any fixed-size visual composed in markup.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Why Astro Cards?
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Every site needs images it cannot author by hand: an Open Graph card per post, a badge per release,
+a ticket per attendee. Astro has no built-in way to produce them, so the usual answer is a separate
+templating layer, either a fixed template you fill with a title and a description, or JSX rendered
+by a library that is not the one your site is built with.
 
-## Purpose
+With **Astro Cards** the template is an ordinary `.astro` component. You write markup and CSS, take
+props, import images with `astro:assets`, and use the fonts you already configured. The integration
+renders it with [takumi](https://takumi.kane.tw) and hands back the URL of an image.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `astro-cards`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+It works both on prerendered pages and on pages rendered on demand.
 
-## What is OIDC Trusted Publishing?
+## Installation
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```sh
+npx astro add astro-cards
+```
 
-## Setup Instructions
+### Manual Install
 
-To properly configure OIDC trusted publishing for this package:
+Install `astro-cards` using your package manager.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```sh
+npm install astro-cards
+```
 
-## DO NOT USE THIS PACKAGE
+Add the integration to your `astro.config.mjs`:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```js
+import { defineConfig } from 'astro/config';
+import cards from 'astro-cards';
 
-## More Information
+export default defineConfig({
+  // ...
+  integrations: [cards()],
+});
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## Usage
 
+### Creating a card
+
+Cards are `.astro` components in `src/cards`. The file name is the card's name, so
+`src/cards/post.astro` is the card `post`, and a card in a subdirectory keeps its path,
+`src/cards/blog/post.astro` being `blog/post`.
+
+```astro
+---
+import type { CardOptions } from 'astro-cards';
+
+interface Props {
+  title: string;
+}
+
+export const card = { width: 1200, height: 630 } satisfies CardOptions;
+
+const { title } = Astro.props;
+---
+
+<div class="card">{title}</div>
+
+<style is:inline>
+  .card {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: #17171a;
+    color: #ffffff;
+    font-size: 64px;
+  }
+</style>
+```
+
+> [!IMPORTANT]  
+> Style blocks in a card must be `is:inline`. Astro hoists a plain `<style>` into a bundled
+> stylesheet that the renderer never sees, so the card would come out unstyled.
+
+### Rendering a card
+
+Call `renderCard` with the card's name and its props. It returns the URL to embed, plus the
+dimensions and MIME type, which is what the Open Graph tags want.
+
+```astro
+---
+import { renderCard } from 'astro-cards/runtime';
+
+const card = await renderCard('post', { title: Astro.props.title });
+---
+
+<meta property="og:image" content={card.src} />
+<meta property="og:image:width" content={card.width} />
+<meta property="og:image:height" content={card.height} />
+<meta property="og:image:type" content={card.type} />
+```
+
+Card names are typed once `astro sync` has run, so an unknown name is a type error and the props are
+checked against the card's own `Props`.
+
+> [!WARNING]  
+> On a page rendered on demand the props travel in the image URL, encoded but not encrypted, and the
+> response is publicly cacheable. Do not pass secrets or personal data.
+
+### Size, format and quality
+
+Each option can be set in three places, and the nearest one wins: the call site beats the card,
+which beats the integration config.
+
+```js
+// astro.config.mjs: the default for every card
+cards({ width: 1200, height: 630, format: 'jpeg', quality: 90 });
+```
+
+```astro
+---
+// the card: a default for this template
+export const card = { width: 400, height: 200, format: 'png' };
+---
+```
+
+```js
+// the call site: this one image
+await renderCard('post', { title }, { width: 800, height: 418 });
+```
+
+Formats are `png`, `jpeg` and `webp`. `quality` runs from 0 to 100 and applies to the lossy formats
+only.
+
+### Fonts
+
+A card's fonts come from the `@font-face` rules in its own markup. A card that declares none renders
+its text in Noto Sans, fetched from Google Fonts.
+
+The easiest source is Astro's fonts API, whose `<Font>` component writes the `@font-face` rules
+straight into the card:
+
+```astro
 ---
+import { Font } from 'astro:assets';
+---
+
+<Font cssVariable="--font-heading" />
+
+<div class="card">Hello</div>
+
+<style is:inline>
+  .card {
+    font-family: var(--font-heading);
+  }
+</style>
+```
+
+Hand-written `@font-face` rules work as well, whether the file sits in `public/` or on another host:
+
+```astro
+<style is:inline>
+  @font-face {
+    font-family: Inter;
+    src: url(/fonts/inter-latin-400.woff2) format('woff2');
+    unicode-range: U+0000-00FF;
+  }
+</style>
+```
+
+Declaring `unicode-range` is worth doing for a family split into subsets, because the renderer then
+loads only the files the text actually needs.
+
+> [!NOTE]  
+> Stylesheet `<link>` elements are not fetched. Faces have to be declared in the card's markup.
+
+### Images
+
+Images imported through `astro:assets` work as they do anywhere else, and so do files in `public/`:
+
+```astro
+---
+import { Image } from 'astro:assets';
+import photo from '../assets/photo.png';
+---
+
+<Image src={photo} width={200} height={200} alt="" />
+
+<img src="/logo.png" width="100" height="100" alt="" />
+
+<style is:inline>
+  .backdrop {
+    background-image: url(/backdrop.png);
+  }
+</style>
+```
+
+Images on other hosts are fetched, and are subject to the same
+[`image.domains`](https://docs.astro.build/en/reference/configuration-reference/#imagedomains) and
+[`image.remotePatterns`](https://docs.astro.build/en/reference/configuration-reference/#imageremotepatterns)
+rules as the rest of your site.
+
+## Options
+
+| Option    | Type                        | Default       | Description                                       |
+| --------- | --------------------------- | ------------- | ------------------------------------------------- |
+| `dir`     | `string`                    | `'src/cards'` | Where card components live, relative to the root. |
+| `width`   | `number`                    | `1200`        | Default pixel width.                              |
+| `height`  | `number`                    | `630`         | Default pixel height.                             |
+| `format`  | `'png' \| 'jpeg' \| 'webp'` | `'jpeg'`      | Default encoding.                                 |
+| `quality` | `number`                    | `90`          | Default encoder quality, 0 to 100, lossy formats. |
+
+## Limitations
+
+A card rendered on demand receives its props through the URL, so they must be
+[serialisable](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): able to be
+translated into a format suitable for transfer over a network. Not every structure is, so there are
+some limitations on what can be passed to `renderCard`.
+
+The following prop types are supported: plain object, `number`, `string`, `boolean`, `null`,
+`undefined`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`,
+`Uint32Array`, and `Infinity`. Repeated and circular references are preserved. The decoded on-demand
+payload is limited to 128 KiB.
+
+Notably, functions and class instances cannot be passed, as they cannot be serialised.
 
-**Maintained for OIDC setup purposes only**
+> [!NOTE]  
+> This applies whenever a card is rendered on demand, which includes every card in `astro dev`. A
+> prerendered build hands props straight to the component, so an unsupported prop can pass
+> `astro build` and fail in `astro dev`.

package/dist/endpoint.d.ts

@@ -0,0 +1,5 @@
+import { APIRoute } from "astro";
+//#region src/endpoint.d.ts
+export declare const prerender = false;
+export declare const GET: APIRoute;
+//#endregion

package/dist/endpoint.js

@@ -0,0 +1,33 @@
+import { r as loadCard, t as decodePayload } from "./payload-CizLlC8p.js";
+import { r as rasterise } from "./render-CzpiUNuk.js";
+import { cards, config } from "virtual:astro-cards";
+//#region src/endpoint.ts
+const prerender = false;
+const GET = async ({ request }) => {
+	const url = new URL(request.url);
+	const origin = config.site ? new URL(config.site).origin : url.origin;
+	const payload = await decodePayload(url.searchParams.get("p") ?? "").catch(() => void 0);
+	if (!payload) return new Response("Bad Request", { status: 400 });
+	const { name, props, ...overrides } = payload;
+	if (!Object.hasOwn(cards, name)) return new Response("Not Found", { status: 404 });
+	const { options, type, render } = await loadCard(name, overrides);
+	const bytes = await rasterise({
+		name,
+		markup: await render(props),
+		...options
+	}, {
+		origin,
+		base: config.base,
+		imageConfig: config.image,
+		assetsPrefix: typeof config.assetsPrefix === "string" ? [config.assetsPrefix] : Object.values(config.assetsPrefix ?? {})
+	});
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	const etag = Array.from(new Uint8Array(digest, 0, 10), (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return new Response(bytes, { headers: {
+		"Content-Type": type,
+		"Cache-Control": "public, max-age=31536000",
+		ETag: `"${etag}"`
+	} });
+};
+//#endregion
+export { GET, prerender };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { a as Format, i as CardOptions, t as CardResult } from "./runtime-BIgJTgv9.js";
+import { AstroIntegration } from "astro";
+//#region src/index.d.ts
+export interface CardsOptions extends CardOptions {
+  /** Where the card components live, relative to the project root. Defaults to `src/cards`. */
+  dir?: string;
+}
+export default function cards(options?: CardsOptions): AstroIntegration;
+//#endregion
+export type { CardOptions, CardResult, Format };

package/dist/index.js

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { writeFileSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { availableParallelism } from "node:os";
+import { join, relative, sep } from "node:path";
+import { json } from "node:stream/consumers";
+import { fileURLToPath } from "node:url";
+import { styleText } from "node:util";
+import { isParentDirectory, stripRequestBase } from "@astrojs/internal-helpers/path";
+//#region src/index.ts
+const ID = "virtual:astro-cards";
+const FALLBACK_ORIGIN = "https://localhost";
+const COLLECTOR = Symbol.for("astro-cards.collector");
+const globals = globalThis;
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function cards(options = {}) {
+	let found = [];
+	let astroConfig;
+	let assetsPrefix;
+	let collector;
+	let cardsDir;
+	let trigger;
+	const pending = /* @__PURE__ */ new Map();
+	return {
+		name: "astro-cards",
+		hooks: {
+			async "astro:config:setup"({ addWatchFile, command, config, createCodegenDir, injectRoute, updateConfig }) {
+				cardsDir = fileURLToPath(new URL(`${options.dir ?? "src/cards"}/`, config.root));
+				found = (await readdir(cardsDir, {
+					recursive: true,
+					withFileTypes: true
+				}).catch((error) => {
+					if (error.code !== "ENOENT") throw error;
+					return [];
+				})).filter((entry) => entry.isFile() && entry.name.endsWith(".astro")).map((entry) => {
+					const path = join(entry.parentPath, entry.name);
+					return {
+						path,
+						name: relative(cardsDir, path).replace(/\.astro$/, "").split(sep).join("/")
+					};
+				}).sort((a, b) => a.name.localeCompare(b.name));
+				let url;
+				if (command === "build") {
+					pending.clear();
+					collector = createServer(async (request, response) => {
+						const file = decodeURIComponent((request.url ?? "/").slice(1));
+						pending.set(file, await json(request));
+						response.end();
+					});
+					collector.listen(0, "127.0.0.1").unref();
+					await once(collector, "listening");
+					url = `http://127.0.0.1:${collector.address().port}/`;
+					globals[COLLECTOR] = url;
+				}
+				if (command === "dev") {
+					trigger = fileURLToPath(new URL("restart", createCodegenDir()));
+					addWatchFile(trigger);
+				}
+				assetsPrefix = config.build.assetsPrefix;
+				updateConfig({ vite: { plugins: [{
+					name: "astro-cards:virtual",
+					enforce: "pre",
+					resolveId: (id) => id === ID ? `\0${ID}` : void 0,
+					load(id) {
+						if (id !== `\0${ID}`) return;
+						const cardsConfig = {
+							width: options.width ?? 1200,
+							height: options.height ?? 630,
+							format: options.format ?? "jpeg",
+							quality: options.quality ?? 90,
+							site: command === "dev" ? void 0 : config.site,
+							base: config.base,
+							assetsDir: config.build.assets,
+							assetsPrefix,
+							image: {
+								domains: config.image.domains,
+								remotePatterns: config.image.remotePatterns
+							},
+							collector: this.environment?.name === "prerender" ? url : void 0
+						};
+						return [
+							"export const cards = {",
+							...found.map(({ name, path }) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(path)}),`),
+							"}",
+							`export const config = ${JSON.stringify(cardsConfig)}`
+						].join("\n");
+					}
+				}] } });
+				if (command === "dev" || config.output === "server" || config.adapter) injectRoute({
+					pattern: "/_cards",
+					entrypoint: new URL("./endpoint.js", import.meta.url),
+					prerender: false
+				});
+			},
+			async "astro:config:done"({ config, injectTypes }) {
+				astroConfig = config;
+				const content = `export {}\ndeclare module 'astro-cards/runtime' {\n  interface Cards {\n${found.map(({ name, path }) => `    ${JSON.stringify(name)}: typeof import(${JSON.stringify(path)}).default`).join("\n")}\n  }\n}\n`;
+				const types = injectTypes({
+					filename: "cards.d.ts",
+					content
+				});
+				if (trigger) await writeFile(types, content);
+			},
+			"astro:server:setup"({ server }) {
+				const touch = (file) => {
+					if (trigger && file.endsWith(".astro") && isParentDirectory(cardsDir, file)) writeFileSync(trigger, String(Date.now()));
+				};
+				server.watcher.on("add", touch).on("unlink", touch);
+			},
+			async "astro:build:done"({ dir, logger }) {
+				collector?.close();
+				delete globals[COLLECTOR];
+				if (!pending.size) return;
+				logger.info(styleText(["bgGreen", "black"], " generating cards "));
+				const { rasterise } = await import("./render-BJFZWw2w.js");
+				const root = fileURLToPath(dir);
+				const readLocal = (pathname) => {
+					const file = join(root, stripRequestBase(pathname, astroConfig.base));
+					if (!isParentDirectory(root, file)) throw new Error(`refusing to read outside the output directory: ${pathname}`);
+					return readFile(file);
+				};
+				const env = {
+					origin: astroConfig.site ? new URL(astroConfig.site).origin : FALLBACK_ORIGIN,
+					base: astroConfig.base,
+					imageConfig: astroConfig.image,
+					assetsPrefix: typeof assetsPrefix === "string" ? [assetsPrefix] : Object.values(assetsPrefix ?? {}),
+					readLocal
+				};
+				const outDir = new URL(`./${astroConfig.build.assets}/`, dir);
+				const cacheDir = new URL("astro-cards/", astroConfig.cacheDir);
+				await mkdir(outDir, { recursive: true });
+				await mkdir(cacheDir, { recursive: true });
+				const unchanged = async (key, dep) => {
+					if (!URL.canParse(key)) return sha(await readLocal(key)) === dep.sha;
+					if (dep.expires && dep.expires > Date.now()) return true;
+					return (await fetch(key, {
+						method: "HEAD",
+						headers: {
+							...dep.etag && { "if-none-match": dep.etag },
+							...dep.modified && { "if-modified-since": dep.modified }
+						},
+						signal: AbortSignal.timeout(3e4),
+						redirect: "manual"
+					})).status === 304;
+				};
+				const reuse = async (file) => {
+					const deps = await readFile(new URL(`./${file}.json`, cacheDir), "utf-8").then((json) => JSON.parse(json)).catch(() => void 0);
+					if (!deps) return void 0;
+					const checks = Object.entries(deps).map(([key, dep]) => unchanged(key, dep));
+					if (!(await Promise.all(checks).catch(() => [false])).every(Boolean)) return void 0;
+					return readFile(new URL(`./${file}`, cacheDir)).catch(() => void 0);
+				};
+				let done = 0;
+				const emit = async (file, card) => {
+					const started = performance.now();
+					const log = (bytes, cached) => {
+						const ms = performance.now() - started;
+						const took = ms < 1e3 ? `${Math.round(ms)}ms` : `${(ms / 1e3).toFixed(2)}s`;
+						const detail = `(${`${Math.round(bytes.length / 1024)}kB`}) ${cached ? "(cached) " : ""}(${took}) (${++done}/${pending.size})`;
+						logger.info(`  ${styleText("green", "▶")} /${astroConfig.build.assets}/${file} ${styleText("dim", detail)}`);
+					};
+					const hit = await reuse(file);
+					if (hit) {
+						await writeFile(new URL(`./${file}`, outDir), hit);
+						return log(hit, true);
+					}
+					const deps = /* @__PURE__ */ new Map();
+					const bytes = await rasterise(card, {
+						...env,
+						readLocal: async (pathname) => {
+							const read = await readLocal(pathname);
+							if (!stripRequestBase(pathname, astroConfig.base).startsWith(`/${astroConfig.build.assets}/`)) deps.set(pathname, { sha: sha(read) });
+							return read;
+						},
+						fetch: async (url, init) => {
+							const response = await fetch(url, init);
+							if (!response.ok) return response;
+							const body = await response.bytes();
+							const maxAge = response.headers.get("cache-control")?.match(/max-age=(\d+)/)?.[1];
+							deps.set(String(url), {
+								sha: sha(body),
+								etag: response.headers.get("etag") ?? void 0,
+								modified: response.headers.get("last-modified") ?? void 0,
+								expires: maxAge ? Date.now() + Number(maxAge) * 1e3 : void 0
+							});
+							return new Response(body, {
+								status: response.status,
+								statusText: response.statusText,
+								headers: response.headers
+							});
+						}
+					});
+					await writeFile(new URL(`./${file}`, outDir), bytes);
+					await writeFile(new URL(`./${file}`, cacheDir), bytes);
+					await writeFile(new URL(`./${file}.json`, cacheDir), JSON.stringify(Object.fromEntries(deps)));
+					log(bytes);
+				};
+				const queue = pending.entries();
+				const start = performance.now();
+				await Promise.all(Array.from({ length: Math.min(availableParallelism(), pending.size) }, async () => {
+					for (const [file, card] of queue) await emit(file, card);
+				}));
+				const total = performance.now() - start;
+				const took = total < 1e3 ? `${Math.round(total)}ms` : `${(total / 1e3).toFixed(2)}s`;
+				logger.info(styleText("green", `✓ Completed in ${took}`));
+			}
+		}
+	};
+}
+//#endregion
+export { cards as default };

package/dist/payload-CizLlC8p.js

@@ -0,0 +1,67 @@
+import { cards, config } from "virtual:astro-cards";
+import { experimental_AstroContainer } from "astro/container";
+import { z } from "astro/zod";
+import { parse, stringifyAsync } from "devalue";
+//#region src/card.ts
+const FORMATS = [
+	"png",
+	"jpeg",
+	"webp"
+];
+const EXT = {
+	png: "png",
+	jpeg: "jpg",
+	webp: "webp"
+};
+const container = await experimental_AstroContainer.create();
+async function loadCard(name, overrides) {
+	const module = await cards[name]();
+	const card = module.card ?? {};
+	const format = overrides.format ?? card.format ?? config.format;
+	return {
+		options: {
+			width: overrides.width ?? card.width ?? config.width,
+			height: overrides.height ?? card.height ?? config.height,
+			format,
+			quality: overrides.quality ?? card.quality ?? config.quality
+		},
+		ext: EXT[format],
+		type: `image/${format}`,
+		render: (props) => container.renderToString(module.default, { props })
+	};
+}
+//#endregion
+//#region src/payload.ts
+const schema = z.strictObject({
+	name: z.string(),
+	props: z.record(z.string(), z.unknown()),
+	width: z.number().int().positive().optional(),
+	height: z.number().int().positive().optional(),
+	format: z.enum(FORMATS).optional(),
+	quality: z.number().min(0).max(100).optional()
+});
+const MAX_DECODED = 131072;
+async function encodePayload(payload) {
+	const serialised = await stringifyAsync(payload).catch((cause) => {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		throw new Error(`astro-cards: card "${payload.name}" got a prop it cannot serialise: ${message}`, { cause });
+	});
+	const source = new Blob([serialised]).stream();
+	const deflated = await new Response(source.pipeThrough(new CompressionStream("deflate-raw"))).bytes();
+	let binary = "";
+	for (const byte of deflated) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+async function decodePayload(value) {
+	const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/"));
+	const source = new Blob([Uint8Array.from(binary, (char) => char.charCodeAt(0))]);
+	let size = 0;
+	const decoded = await new Response(source.stream().pipeThrough(new DecompressionStream("deflate-raw")).pipeThrough(new TransformStream({ transform(chunk, controller) {
+		size += chunk.byteLength;
+		if (size > MAX_DECODED) throw new Error("payload is too large");
+		controller.enqueue(chunk);
+	} }))).text();
+	return schema.parse(parse(decoded));
+}
+//#endregion
+export { encodePayload as n, loadCard as r, decodePayload as t };

package/dist/render-BJFZWw2w.js

@@ -0,0 +1,2 @@
+import { r as rasterise } from "./render-CzpiUNuk.js";
+export { rasterise };

package/dist/render-CzpiUNuk.js

@@ -0,0 +1,178 @@
+import { appendForwardSlash } from "@astrojs/internal-helpers/path";
+import { isRemoteAllowed } from "@astrojs/internal-helpers/remote";
+import { defaultMaxFetchBytes, fetchOk, googleFonts, readBodyLimited } from "@takumi-rs/helpers";
+import { fromHtml } from "@takumi-rs/helpers/html";
+import { render } from "takumi-js";
+//#region src/render.ts
+const URL_FUNCTION = /url\(\s*(['"]?)(.*?)\1\s*\)/g;
+const COMMENT = /\/\*[\s\S]*?\*\//g;
+const FONT_FACE = /@font-face\s*\{([^}]*)\}/g;
+/** Finds every image a card references, mapping the raw source to an absolute URL. */
+function collectSources(node, css, base) {
+	const found = /* @__PURE__ */ new Map();
+	const add = (raw, value = raw) => {
+		if (value.startsWith("data:") || value.startsWith("#")) return;
+		const url = new URL(value, base);
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`unsupported image URL "${value}"`);
+		found.set(raw, url.href);
+	};
+	const scan = (value) => {
+		if (typeof value !== "string") return;
+		for (const match of value.matchAll(URL_FUNCTION)) {
+			const url = match[2]?.trim();
+			if (url) add(url);
+		}
+	};
+	const visit = (node) => {
+		for (const value of Object.values(node.style ?? {})) scan(value);
+		for (const value of Object.values(node.preset ?? {})) scan(value);
+		scan(node.tw);
+		if (node.type === "image" && typeof node.src === "string") add(node.src, node.attributes?.src);
+		if (node.type === "container") for (const child of node.children ?? []) visit(child);
+	};
+	visit(node);
+	for (const sheet of css) scan(sheet.replace(COMMENT, "").replace(FONT_FACE, ""));
+	return found;
+}
+const hasText = (node) => {
+	if (node.type === "text") return Boolean(node.text?.trim());
+	return node.type === "container" ? (node.children ?? []).some(hasText) : false;
+};
+function parseUnicodeRange(value) {
+	const ranges = [];
+	for (const raw of value.split(",")) {
+		const token = raw.trim().replace(/^U\+/i, "");
+		if (!token) continue;
+		if (token.includes("-")) {
+			const [lo, hi] = token.split("-");
+			if (lo && hi) ranges.push([parseInt(lo, 16), parseInt(hi, 16)]);
+		} else if (token.includes("?")) ranges.push([parseInt(token.replaceAll("?", "0"), 16), parseInt(token.replaceAll("?", "F"), 16)]);
+		else {
+			const codepoint = parseInt(token, 16);
+			ranges.push([codepoint, codepoint]);
+		}
+	}
+	return ranges;
+}
+function hash(value) {
+	let h = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		h ^= value.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+/** Adapted from the parser inside `googleFonts` in `@takumi-rs/helpers` 2.13.5 (MIT). */
+function collectFonts(css, base) {
+	const faces = [];
+	for (const sheet of css) for (const [, body] of sheet.replace(COMMENT, "").matchAll(FONT_FACE)) {
+		const url = body?.match(/src:[^;]*?url\(([^)]+)\)/)?.[1]?.replace(/['"]/g, "").trim();
+		const family = body?.match(/font-family:\s*['"]?([^'";]+)['"]?/)?.[1]?.trim();
+		if (!body || !url || !family) continue;
+		const range = body.match(/unicode-range:\s*([^;]+)/)?.[1];
+		const weight = body.match(/font-weight:\s*(\d+)(?:\s+(\d+))?/);
+		const ranges = parseUnicodeRange(range ?? "");
+		faces.push({
+			family,
+			subset: `s${hash(ranges.map(([lo, hi]) => `${lo}-${hi}`).join(","))}`,
+			url: new URL(url, base).href,
+			weight: weight && !weight[2] ? Number(weight[1]) : void 0,
+			style: body.match(/font-style:\s*([a-z]+)/i)?.[1],
+			ranges
+		});
+	}
+	const identity = (face) => `${face.family} ${face.subset}:${face.style ?? ""}:${face.url}`;
+	const weights = /* @__PURE__ */ new Map();
+	for (const face of faces) {
+		const id = identity(face);
+		weights.set(id, (weights.get(id) ?? /* @__PURE__ */ new Set()).add(face.weight));
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const face of faces) {
+		const id = identity(face);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		merged.push((weights.get(id)?.size ?? 0) > 1 ? {
+			...face,
+			weight: void 0
+		} : face);
+	}
+	return merged.map(({ family, subset, ...face }) => ({
+		name: `${family} ${subset}`,
+		subsetOf: family,
+		subsetRank: face.ranges.length ? Math.min(...face.ranges.map(([lo]) => lo)) : 4294967295,
+		key: `${family} ${subset}:${face.weight ?? ""}:${face.style ?? ""}:${face.url}`,
+		...face
+	}));
+}
+async function rasterise(card, env) {
+	const cdns = (env.assetsPrefix ?? []).map((prefix) => new URL(appendForwardSlash(prefix)));
+	const findCdn = (url) => cdns.find((cdn) => url.href.startsWith(cdn.href));
+	const resolve = async (url, init) => {
+		const absolute = new URL(url, env.origin);
+		if (env.readLocal) {
+			const cdn = findCdn(absolute);
+			let pathname;
+			if (cdn) pathname = absolute.pathname.slice(cdn.pathname.length - 1);
+			else if (absolute.origin === env.origin) pathname = absolute.pathname;
+			if (pathname !== void 0) return new Response(await env.readLocal(decodeURIComponent(pathname)));
+		}
+		return (env.fetch ?? fetch)(absolute.href, init);
+	};
+	const allowUrl = (url) => {
+		const parsed = URL.parse(url);
+		if (!parsed) return false;
+		if (parsed.origin === env.origin || findCdn(parsed)) return true;
+		return isRemoteAllowed(url, env.imageConfig);
+	};
+	try {
+		const { node, css } = fromHtml(card.markup);
+		const base = new URL(appendForwardSlash(env.base), env.origin).href;
+		const fonts = collectFonts(css, base).map(({ url, ...face }) => ({
+			...face,
+			data: () => fetchOk(url, { fetch: resolve }).then((r) => readBodyLimited(r, defaultMaxFetchBytes))
+		}));
+		if (!fonts.length && hasText(node)) {
+			const name = "Noto Sans";
+			const fallback = await googleFonts([{
+				name,
+				weight: "100..900"
+			}]).catch((cause) => {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				throw new Error(`error fetching ${name} from Google Fonts: ${message}`, { cause });
+			});
+			if (!fallback.length) throw new Error(`Google Fonts returned no faces for ${name}`);
+			fonts.push(...fallback);
+		}
+		const sources = [];
+		for (const [src, url] of collectSources(node, css, base)) {
+			const data = async () => readBodyLimited(await fetchOk(url, {
+				fetch: resolve,
+				allowUrl
+			}), defaultMaxFetchBytes);
+			sources.push({
+				src,
+				data
+			});
+		}
+		return await render(node, {
+			width: card.width,
+			height: card.height,
+			format: card.format,
+			quality: card.quality,
+			fonts,
+			css,
+			images: {
+				sources,
+				fetch: resolve,
+				allowUrl
+			}
+		});
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		throw new Error(`astro-cards: card "${card.name}" failed: ${message}`, { cause });
+	}
+}
+//#endregion
+export { collectSources as n, rasterise as r, collectFonts as t };

package/dist/runtime-BIgJTgv9.d.ts

@@ -0,0 +1,28 @@
+import { ComponentProps } from "astro/types";
+//#region src/card.d.ts
+declare const FORMATS: readonly ["png", "jpeg", "webp"];
+type Format = (typeof FORMATS)[number];
+interface CardOptions {
+  /** Pixel width of the image. Defaults to 1200. */
+  width?: number;
+  /** Pixel height of the image. Defaults to 630. */
+  height?: number;
+  /** Image encoding. Defaults to `jpeg`. */
+  format?: Format;
+  /** Encoder quality from 0 to 100 for lossy formats. Defaults to 90. */
+  quality?: number;
+}
+//#endregion
+//#region src/runtime.d.ts
+interface CardResult {
+  src: string;
+  width: number;
+  height: number;
+  type: string;
+}
+/** The project's cards, filled in by the declaration `astro sync` generates. */
+interface Cards {}
+/** Resolves a card to what a page embeds: its `src`, size and MIME type. */
+declare function renderCard<K extends keyof Cards & string>(name: K, props: ComponentProps<Cards[K]>, options?: CardOptions): Promise<CardResult>;
+//#endregion
+export { Format as a, CardOptions as i, Cards as n, renderCard as r, CardResult as t };

package/dist/runtime.d.ts

@@ -0,0 +1,2 @@
+import { n as Cards, r as renderCard, t as CardResult } from "./runtime-BIgJTgv9.js";
+export { CardResult, Cards, renderCard };

package/dist/runtime.js

@@ -0,0 +1,56 @@
+import { n as encodePayload, r as loadCard } from "./payload-CizLlC8p.js";
+import { joinPaths, prependForwardSlash, removeTrailingForwardSlash } from "@astrojs/internal-helpers/path";
+import { cards, config } from "virtual:astro-cards";
+//#region src/runtime.ts
+const INVALID_CHAR_REGEX = /[\u0000-\u001F"#$%&*+,:;<=>?[\]^`{|}\u007F]/g;
+const COLLECTOR = Symbol.for("astro-cards.collector");
+const globals = globalThis;
+/** Resolves a card to what a page embeds: its `src`, size and MIME type. */
+async function renderCard(name, props, options = {}) {
+	if (!Object.hasOwn(cards, name)) {
+		const known = Object.keys(cards).join(", ");
+		throw new Error(`astro-cards: no card named "${name}". Known cards: ${known || "(none)"}`);
+	}
+	const { options: resolved, ext, type, render } = await loadCard(name, options);
+	const collector = config.collector ?? globals[COLLECTOR];
+	if (collector) {
+		const markup = await render(props);
+		const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify({
+			markup,
+			...resolved
+		})));
+		const hash = Array.from(new Uint8Array(digest, 0, 10), (byte) => byte.toString(16).padStart(2, "0")).join("");
+		const key = name;
+		const file = `${key.slice(key.lastIndexOf("/") + 1).replace(INVALID_CHAR_REGEX, "_")}.${hash}.${ext}`;
+		const card = {
+			name,
+			markup,
+			...resolved
+		};
+		await fetch(new URL(file, collector), {
+			method: "POST",
+			body: JSON.stringify(card)
+		});
+		const path = prependForwardSlash(joinPaths(config.assetsDir, file));
+		const prefix = typeof config.assetsPrefix === "string" ? config.assetsPrefix : config.assetsPrefix?.[ext] || config.assetsPrefix?.fallback;
+		return {
+			src: prefix ? `${removeTrailingForwardSlash(prefix)}${path}` : joinPaths(config.base, path),
+			width: resolved.width,
+			height: resolved.height,
+			type
+		};
+	}
+	const payload = await encodePayload({
+		name,
+		props,
+		...options
+	});
+	return {
+		src: `${joinPaths(config.base, "_cards")}?p=${payload}`,
+		width: resolved.width,
+		height: resolved.height,
+		type
+	};
+}
+//#endregion
+export { renderCard };

package/package.json

@@ -1,10 +1,72 @@
 {
   "name": "astro-cards",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for astro-cards",
+  "description": "Generate Open Graph images from Astro components, at build time or on demand.",
+  "version": "1.0.0",
+  "type": "module",
+  "author": "Adam Bouqdib <adam@abemedia.co.uk>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abemedia/astro-cards.git"
+  },
+  "bugs": "https://github.com/abemedia/astro-cards/issues",
+  "homepage": "https://github.com/abemedia/astro-cards#readme",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./runtime": "./dist/runtime.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "astro-integration",
+    "withastro",
+    "astro",
+    "image",
+    "images",
+    "ui",
+    "seo",
+    "open-graph",
+    "opengraph",
+    "social-image",
+    "og-image",
+    "social-card",
+    "twitter-card",
+    "image-generation",
+    "takumi"
+  ],
+  "peerDependencies": {
+    "astro": "^5.1.5 || ^6.0.0 || ^7.0.0"
+  },
+  "dependencies": {
+    "@astrojs/internal-helpers": "^0.11.0",
+    "@takumi-rs/helpers": "2.13.6",
+    "devalue": "^5.9.2",
+    "takumi-js": "2.13.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@stagelint/stagelint": "^0.1.5",
+    "@types/jest-image-snapshot": "^6.4.1",
+    "@types/node": "^22.20.1",
+    "astro": "^7.3.1",
+    "jest-image-snapshot": "^6.5.2",
+    "sharp": "^0.35.4",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/runtime.ts src/endpoint.ts --no-fixed-extension --deps.never-bundle virtual:astro-cards",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "biome format --write .",
+    "lint": "biome lint --write .",
+    "check": "biome check . && tsc --noEmit"
+  }
+}