@atelic-action/ui 3.5.0 → 3.6.0

package/README.md

@@ -98,7 +98,7 @@ Every export, grouped by the entry it is imported from. The gallery column links
 | `SocialStrip` | `@atelic-action/ui/sections` | A static grid of the business's social photos linking to the profile, never a live embed | [#social-strip](https://ui.atelic.me/#social-strip) |
 | `SplitSection` | `@atelic-action/ui/sections` | The two column band: copy beside copy, or media beside copy | [#split-section](https://ui.atelic.me/#split-section) |
 | `SiteConfig` and its member types, `formatClock`, `formatHoursRange`, `isClosed`, `isHoneypotFilled`, `trackEvent` | `@atelic-action/ui/sections` | The site contract the sections read, and the hours, honeypot, and lead event helpers | none |
-| `ImageFrame`, `ProseBlocks`, `QuoteCard`, `StarRow`, `TickList` | `@atelic-action/ui/primitives` | The marketing primitives: a framed image, prose blocks, a quote card, a row of filled stars, a tick list | [#marketing-primitives](https://ui.atelic.me/#marketing-primitives) |
+| `ImageFrame`, `ProseBlocks`, `QuoteCard`, `StarRow`, `TickList` | `@atelic-action/ui/primitives` | The marketing primitives: a framed image, prose blocks (headings at two levels, paragraphs, lists, and a figure that is an image or a silent looping clip played only while on screen), a quote card, a row of filled stars, a tick list | [#marketing-primitives](https://ui.atelic.me/#marketing-primitives) |
 | `SiteShell` | `@atelic-action/ui/chrome` | A marketing page's whole chrome: skip link, header, main, footer, sticky bar, mounting the base path provider | none |
 | `BasePathProvider`, `useBasePath`, `useWithBase`, `joinBase`, `stripBase`, `hasBase`, `normalizeBasePath` | `@atelic-action/ui/routing` | The base path a site is served under, read by Button, Chip, and every section that builds a link | none |
 | `joinBase`, `stripBase`, `hasBase`, `normalizeBasePath` | `@atelic-action/ui/routing/base-path` | The same four pure helpers, built, for what Node runs (a Playwright spec, a script) | none |
@@ -405,6 +405,7 @@ The package installs the scripts every artifact site used to carry as files, so
 | `atelic-seal-document <config.json> [out.json]` | Seals a document into the payload that `@atelic-action/artifact`'s `Gate` reads, one wrapped key for each reader. The payload names no one: no address, and readers numbered `r1`, `r2` whatever the config calls them | `seal` |
 | `atelic-clean-sitemap` | Strips fragment and trailing slash duplicates out of `dist/client/sitemap.xml`; says so and passes when a based build wrote none | A marketing site's `build`, after vite |
 | `atelic-check-base-path` | Fails the build when a root path in `dist/client` lacks the base path, or `vercel.json` lacks (or strays from) the two rewrites a based cut needs; a `VITE_BASE_PATH` rehearsal only warns about `vercel.json` off Vercel | Last step of a marketing site's `build` |
+| `atelic-check-images` | Fails the build when `public/images` holds an image over 250 KB, a PNG over 64 KB, or a JPEG that is not a sharing card (`og.jpg` or `<name>-og.jpg`): every photo ships as WebP at about 2x its rendered width (template-marketing's CLAUDE.md, Image budget) | First step of a marketing site's `build` |
 | `atelic-contact-canary` | Posts a token bearing test message to `$SITE_URL/api/contact` and passes only on a Resend id and the expected destination (`CONTACT_EXPECTED_TO`, `CONTACT_CANARY_TOKEN`); a `.invalid` `SITE_URL` is the off switch | `check:contact`, run daily by the canary workflow |
 
 A site's scripts, whole:

package/bin/atelic-check-images.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-check-images: fails a build whose public/images holds a photo over budget or a JPEG that is not a sharing card.
+import { main } from "../src/scripts/check-images";
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "3.5.0",
+	"version": "3.6.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -19,6 +19,7 @@
 	"bin": {
 		"atelic-check-access": "./bin/atelic-check-access.ts",
 		"atelic-check-base-path": "./bin/atelic-check-base-path.ts",
+		"atelic-check-images": "./bin/atelic-check-images.ts",
 		"atelic-check-links": "./bin/atelic-check-links.ts",
 		"atelic-check-wall": "./bin/atelic-check-wall.ts",
 		"atelic-clean-sitemap": "./bin/atelic-clean-sitemap.ts",

package/src/primitives/ProseBlocks.tsx

@@ -1,15 +1,127 @@
+import { useEffect, useRef, useState } from "react";
+import { useWithBase } from "../routing/BasePathProvider";
+
 /**
- * One block of ported prose. A deliberately tiny vocabulary — headings,
- * paragraphs, lists — because that is what survives extraction from a CMS
- * intact, and because anything richer invites rewriting content that was
- * meant to be carried across verbatim.
+ * One block of prose carried as data. A deliberately tiny vocabulary:
+ * headings, paragraphs, lists, and a figure, because that is what survives
+ * extraction from a CMS intact, and because anything richer invites rewriting
+ * content that was meant to be carried across verbatim.
  */
 export interface ProseBlock {
-	type: "h" | "p" | "ul";
+	type: "h" | "p" | "ul" | "figure";
 	/** Present for "h" and "p". */
 	text?: string;
+	/**
+	 * For "h": the heading's level under the page's own h1, where the
+	 * component's `headingLevel` is the default. A post with sections and
+	 * sub sections marks the sub sections 3 and leaves the rest alone.
+	 */
+	level?: 2 | 3;
 	/** Present for "ul". */
 	items?: string[];
+	/**
+	 * Present for "figure": the file the figure shows. A `.mp4` or `.webm`
+	 * plays as a silent loop (a short clip of an exercise, say), anything
+	 * else is an image. Both load lazily, since a figure sits in running prose
+	 * below the fold.
+	 */
+	src?: string;
+	/** For "figure": what the figure shows, for a reader who cannot see it. */
+	alt?: string;
+	/** For "figure": a line under it. */
+	caption?: string;
+	/**
+	 * For "figure": the file's own width and height in pixels. With both, the
+	 * figure holds its shape before the file arrives (no layout shift), and a
+	 * tall one is narrowed so it never runs taller than most of the screen.
+	 */
+	width?: number;
+	height?: number;
+	/** For a clip: a still shown until it plays, and to a reader who prefers reduced motion. */
+	poster?: string;
+}
+
+const CLIP = /\.(mp4|webm)([?#].*)?$/i;
+
+/**
+ * The box a figure's file draws in: its own shape, and never taller than most
+ * of the screen, so a portrait clip in a text column does not fill a desktop
+ * from top to bottom. Nothing without both dimensions.
+ */
+function frameStyle(width?: number, height?: number) {
+	if (!width || !height) return undefined;
+	return {
+		aspectRatio: `${width} / ${height}`,
+		maxWidth: `min(100%, calc(75vh * ${width} / ${height}))`,
+	};
+}
+
+/**
+ * A silent looping clip. It plays only while it is on screen and pauses when
+ * it leaves, and it fetches nothing until it first comes into view, so a post
+ * with a clip beside every exercise costs nothing up front. A reader who asked
+ * for reduced motion gets it still, with controls to start it.
+ */
+function Clip({
+	src,
+	alt,
+	poster,
+	style,
+}: {
+	src: string;
+	alt?: string;
+	poster?: string;
+	style?: ReturnType<typeof frameStyle>;
+}) {
+	const ref = useRef<HTMLVideoElement>(null);
+	const [still, setStill] = useState(false);
+	useEffect(() => {
+		const video = ref.current;
+		if (!video) return;
+		if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) {
+			setStill(true);
+			return;
+		}
+		// A pause that interrupts a pending play rejects it with an AbortError;
+		// that is the reader scrolling past, not autoplay being refused.
+		let observer: IntersectionObserver | undefined;
+		const play = () =>
+			video.play()?.catch((err: unknown) => {
+				if ((err as { name?: string } | null)?.name === "AbortError") return;
+				// Autoplay refused: hand the clip to the reader and stop steering it.
+				setStill(true);
+				observer?.disconnect();
+			});
+		if (typeof IntersectionObserver === "undefined") {
+			play();
+			return;
+		}
+		observer = new IntersectionObserver(
+			(entries) => {
+				if (entries[entries.length - 1]?.isIntersecting) play();
+				else video.pause();
+			},
+			{ rootMargin: "200px 0px" },
+		);
+		observer.observe(video);
+		return () => observer?.disconnect();
+	}, []);
+	return (
+		// biome-ignore lint/a11y/useMediaCaption: a silent loop has no audio to caption; the figcaption and aria-label carry the words
+		<video
+			ref={ref}
+			src={src}
+			poster={poster}
+			aria-label={alt}
+			style={style}
+			loop
+			muted
+			playsInline
+			controls={still}
+			// A still clip never plays, so without a poster it needs its first frame loaded.
+			preload={still && !poster ? "metadata" : "none"}
+		/>
+	);
 }
 
 export interface ProseBlocksProps {
@@ -33,15 +145,52 @@ export interface ProseBlocksProps {
  */
 export function ProseBlocks({ blocks, headingLevel = "h2", className }: ProseBlocksProps) {
 	const Heading = headingLevel;
+	const withBase = useWithBase();
 	return (
 		<div className={["prose-blocks", className].filter(Boolean).join(" ")}>
 			{blocks.map((block, i) => {
 				if (block.type === "h") {
+					const Tag = block.level ? (`h${block.level}` as const) : Heading;
 					return (
-						// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
-						<Heading className="pb-heading" key={`h-${i}-${block.text?.slice(0, 24)}`}>
+						<Tag
+							className={["pb-heading", block.level === 3 ? "pb-h3" : ""].filter(Boolean).join(" ")}
+							// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+							key={`h-${i}-${block.text?.slice(0, 24)}`}
+						>
 							{block.text}
-						</Heading>
+						</Tag>
+					);
+				}
+				if (block.type === "figure") {
+					const src = block.src ? withBase(block.src) : "";
+					const style = frameStyle(block.width, block.height);
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+						<figure className="pb-figure" key={`figure-${i}-${src.slice(-24)}`}>
+							{!src ? (
+								<div className="ph">{block.alt ?? "Figure"}</div>
+							) : CLIP.test(src) ? (
+								<Clip
+									src={src}
+									alt={block.alt}
+									poster={block.poster ? withBase(block.poster) : undefined}
+									style={style}
+								/>
+							) : (
+								<img
+									src={src}
+									alt={block.alt ?? ""}
+									width={block.width}
+									height={block.height}
+									style={style}
+									loading="lazy"
+									decoding="async"
+								/>
+							)}
+							{block.caption ? (
+								<figcaption className="pb-caption">{block.caption}</figcaption>
+							) : null}
+						</figure>
 					);
 				}
 				if (block.type === "ul") {

package/src/scripts/check-images.ts

@@ -0,0 +1,96 @@
+/**
+ * Fails the build when a photo in public/images is over the house budget or
+ * ships as JPEG where WebP belongs. The rule is template-marketing's CLAUDE.md,
+ * Image budget: every photo ships as WebP at quality about 75, sized to about
+ * 2x its rendered width, and the Open Graph cards alone stay JPEG, because
+ * some link previews still will not read WebP. A card is any JPEG whose file
+ * name is `og` or ends in `-og`.
+ *
+ * Usage: atelic-check-images   (from the site's root)
+ * Exits 1 on any problem.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/** Where a site keeps the images it serves, from the site's root. */
+export const IMAGES_ROOT = "public/images";
+
+/** The most any one image may weigh, in bytes. */
+export const IMAGE_BUDGET = 250 * 1024;
+
+/** A PNG past this is a photo saved in the wrong format; a mark or a logo is far smaller. */
+export const PNG_BUDGET = 64 * 1024;
+
+export interface ImageFile {
+	/** The path from the site's root. */
+	path: string;
+	bytes: number;
+}
+
+export interface ImageReport {
+	checked: number;
+	problems: string[];
+}
+
+const CARD = /(^|\/)([\w-]+-)?og\.jpe?g$/i;
+
+/** Whether a JPEG is a sharing card, the one place JPEG still belongs. */
+export function isCard(path: string): boolean {
+	return CARD.test(path);
+}
+
+const kb = (bytes: number) => `${Math.round(bytes / 1024)} KB`;
+
+/** The audit, kept pure so it can be tested without a site. */
+export function auditImages(files: ImageFile[]): ImageReport {
+	const problems: string[] = [];
+	for (const file of files) {
+		const lower = file.path.toLowerCase();
+		if (/\.jpe?g$/.test(lower) && !isCard(file.path)) {
+			problems.push(
+				`${file.path} ships as JPEG (${kb(file.bytes)}); convert it to WebP, or name it og.jpg or <name>-og.jpg if it is a sharing card`,
+			);
+		}
+		if (lower.endsWith(".png") && file.bytes > PNG_BUDGET) {
+			problems.push(
+				`${file.path} is a ${kb(file.bytes)} PNG; a photo ships as WebP, and a mark or a logo stays under ${kb(PNG_BUDGET)}`,
+			);
+		}
+		if (file.bytes > IMAGE_BUDGET) {
+			problems.push(
+				`${file.path} weighs ${kb(file.bytes)}, over the ${kb(IMAGE_BUDGET)} budget; size it to about 2x its rendered width at quality about 75`,
+			);
+		}
+	}
+	return { checked: files.length, problems };
+}
+
+const IMAGE = /\.(webp|avif|jpe?g|png|gif|svg)$/i;
+
+function imageFiles(dir: string, root: string): ImageFile[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) return imageFiles(path, root);
+		if (!IMAGE.test(entry.name)) return [];
+		return [{ path: join(IMAGES_ROOT, path.slice(root.length + 1)), bytes: statSync(path).size }];
+	});
+}
+
+/** The command: audits the images of the site in `cwd`. */
+export function main(cwd: string = process.cwd()): void {
+	const root = resolve(cwd, IMAGES_ROOT);
+	if (!existsSync(root)) {
+		console.log(`[images] no ${IMAGES_ROOT} in ${cwd}; nothing to check`);
+		return;
+	}
+	const report = auditImages(imageFiles(root, root));
+	if (report.problems.length > 0) {
+		for (const problem of report.problems) console.error(`[images] ${problem}`);
+		const count = report.problems.length;
+		console.error(
+			`[images] ${count} problem${count === 1 ? "" : "s"}; the budget is template-marketing's CLAUDE.md, Image budget`,
+		);
+		process.exit(1);
+	}
+	console.log(`[images] ${report.checked} images checked, all within budget`);
+}

package/src/styles/primitives.css

@@ -223,6 +223,36 @@
 		margin-top: 0;
 	}
 
+	/* A sub section heading sits closer to its section and steps down a size. */
+	.atelic-ui .pb-heading.pb-h3 {
+		margin: 28px 0 10px;
+		font-size: 1.02rem;
+	}
+
+	/* A figure in running prose: the image or the silent clip at the column's
+	   width, a rounded frame, and a caption in the body's quiet color. */
+	.atelic-ui .pb-figure {
+		margin: 24px 0;
+	}
+
+	.atelic-ui .pb-figure img,
+	.atelic-ui .pb-figure video {
+		display: block;
+		width: 100%;
+		height: auto;
+		margin-inline: auto;
+		object-fit: cover;
+		border-radius: 14px;
+		background: var(--surface-alt, var(--surface));
+	}
+
+	.atelic-ui .pb-caption {
+		margin-top: 10px;
+		font-size: 0.9rem;
+		line-height: 1.5;
+		color: var(--neutral-600, var(--neutral-700));
+	}
+
 	.atelic-ui .pb-body {
 		margin: 0 0 16px;
 		font-size: 1rem;