wiki-formant 0.112.0 → 0.113.0

package/README.md

@@ -466,6 +466,25 @@ return new ImageResponse(<SocialCard {...{ title, eyebrow, description }} {...fi
 - Fonts stay with the site: Next traces a font file only from a literal path in the app, and satori reads TTF or OTF.
 - `wiki-formant/seeded`'s `hashStr` and `seededRandom` are the deterministic randomness the art draws from, identical on server and browser.
 
+## Page banners
+
+`wiki-formant/banner`: the banner a page is headed with, its own picture or art seeded by the page.
+
+```tsx
+import { PageBanner, BannerArt } from 'wiki-formant/banner';
+
+<PageBanner seed={page.title + page.tagPath} picture={banner && <Image src={banner} alt="" fill preload sizes="100vw" />}>
+  <Breadcrumbs items={crumbs} />
+  <h1>{page.title}</h1>
+</PageBanner>
+<span className="card-thumb"><BannerArt seed={page.title + page.tagPath} /></span>
+```
+
+- Every page has a banner: a page without a picture gets art seeded by `seed`, the same on every render, server and browser. Seed it as the page's card thumbnail is seeded, so the two match.
+- The art is inline SVG with a class per role, coloured by custom properties: `--banner-from` and `--banner-to` the gradient (transparent unset), `--banner-mid` the blobs and half the shapes (`--ui-muted` unset), `--banner-ink` the rest and the dots (`--ui-accent` unset), over `--banner-field` (`--ui-surface` unset). A category's palette or a section's band is a style on the frame.
+- `mark` replaces the triangle with a wiki's own shape, as a path from its anchor, size and generator. `fill-opacity` on a role's class dims it under a title.
+- The frame's 4:1 is a floor, not a height (`base.css`): the trail and title grow it rather than being cropped.
+
 ## Revisions and history
 
 `wiki-formant/revisions`: what changed between two versions of a page, and which bump to ask for. `wiki-formant/history`: what each revision changed, as a history view shows it.

package/dist/banner.d.ts

@@ -0,0 +1,35 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+/**
+ * The art's third kind of shape, as a path: a wiki's own mark. Given its
+ * anchor, its size and the generator, so a mark that turns draws its turn
+ * from the same sequence. The default is a triangle round the anchor.
+ */
+export type BannerMark = (x: number, y: number, size: number, rand: () => number) => string;
+/**
+ * The seeded field: a gradient at a seeded angle, three soft blobs, five to
+ * eight shapes, four bright dots. Its colours are custom properties
+ * (`base.css`): `--banner-from` and `--banner-to` the gradient, transparent
+ * unless set, `--banner-mid` the blobs and half the shapes, `--banner-ink`
+ * the other half and the dots.
+ */
+export declare function BannerArt({ seed, mark, className }: {
+    seed: string;
+    mark?: BannerMark;
+    className?: string;
+}): ReactElement;
+/**
+ * A page's header: its picture, else its art, with the page's trail and title
+ * over it. `picture` is the app's own image element (`next/image` with `fill`,
+ * say), since this package has no `next`; it fills the frame. The frame's
+ * height is a floor of 4:1 that grows with what sits on it (`base.css`), so a
+ * long title on a phone never loses its trail. `style` carries a palette's
+ * custom properties.
+ */
+export declare function PageBanner({ seed, picture, mark, className, style, children }: {
+    seed: string;
+    picture?: ReactNode;
+    mark?: BannerMark;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): ReactElement;

package/dist/banner.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { hashStr, seededRandom } from './seeded.js';
+const W = 800;
+const H = 200;
+const px = (v) => Math.round(v);
+const op = (v) => v.toFixed(2);
+const triangle = (x, y, s, rand) => `M${Array.from({ length: 3 }, () => `${px(x + rand() * s * 2 - s)} ${px(y + rand() * s * 2 - s)}`).join('L')}Z`;
+// Static strings, so a class checker sees every one.
+const FILL = ['banner-art__mid', 'banner-art__ink'];
+const LINE = ['banner-art__mid-line', 'banner-art__ink-line'];
+/**
+ * The seeded field: a gradient at a seeded angle, three soft blobs, five to
+ * eight shapes, four bright dots. Its colours are custom properties
+ * (`base.css`): `--banner-from` and `--banner-to` the gradient, transparent
+ * unless set, `--banner-mid` the blobs and half the shapes, `--banner-ink`
+ * the other half and the dots.
+ */
+export function BannerArt({ seed, mark = triangle, className = 'banner-art' }) {
+    const hash = hashStr(seed);
+    const rand = seededRandom(hash);
+    const id = `banner-${hash.toString(36)}`;
+    const shapes = [];
+    const angle = Math.floor(rand() * 360);
+    for (let i = 0; i < 3; i++) {
+        shapes.push(_jsx("circle", { className: FILL[0], cx: px(rand() * W), cy: px(rand() * H), r: px(60 + rand() * 120), opacity: op(0.15 + rand() * 0.2) }, `blob${i}`));
+    }
+    const count = 5 + Math.floor(rand() * 4);
+    for (let i = 0; i < count; i++) {
+        const x = rand() * W;
+        const y = rand() * H;
+        const tone = i % 2 === 0 ? 1 : 0;
+        const opacity = op(0.12 + rand() * 0.25);
+        const kind = Math.floor(rand() * 4);
+        const key = `shape${i}`;
+        if (kind === 0) {
+            shapes.push(_jsx("circle", { className: FILL[tone], cx: px(x), cy: px(y), r: px(8 + rand() * 40), opacity: opacity }, key));
+        }
+        else if (kind === 1) {
+            const w = px(20 + rand() * 80), h = px(15 + rand() * 50), rx = px(rand() * 12);
+            const turn = px(rand() * 60 - 30);
+            shapes.push(_jsx("rect", { className: FILL[tone], x: px(x), y: px(y), width: w, height: h, rx: rx, opacity: opacity, transform: `rotate(${turn} ${px(x)} ${px(y)})` }, key));
+        }
+        else if (kind === 2) {
+            shapes.push(_jsx("path", { className: FILL[tone], d: mark(x, y, 15 + rand() * 35, rand), opacity: opacity }, key));
+        }
+        else {
+            const r = px(12 + rand() * 30);
+            shapes.push(_jsx("circle", { className: LINE[tone], cx: px(x), cy: px(y), r: r, strokeWidth: (2 + rand() * 4).toFixed(1), opacity: opacity }, key));
+        }
+    }
+    for (let i = 0; i < 4; i++) {
+        shapes.push(_jsx("circle", { className: FILL[1], cx: px(rand() * W), cy: px(rand() * H), r: px(2 + rand() * 6), opacity: op(0.4 + rand() * 0.4) }, `dot${i}`));
+    }
+    return (_jsxs("svg", { className: className, viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: "xMidYMid slice", "aria-hidden": true, focusable: "false", children: [_jsx("defs", { children: _jsxs("linearGradient", { id: id, gradientTransform: `rotate(${angle})`, children: [_jsx("stop", { offset: "0%", className: "banner-art__from" }), _jsx("stop", { offset: "100%", className: "banner-art__to" })] }) }), _jsx("rect", { width: W, height: H, fill: `url(#${id})` }), shapes] }));
+}
+/**
+ * A page's header: its picture, else its art, with the page's trail and title
+ * over it. `picture` is the app's own image element (`next/image` with `fill`,
+ * say), since this package has no `next`; it fills the frame. The frame's
+ * height is a floor of 4:1 that grows with what sits on it (`base.css`), so a
+ * long title on a phone never loses its trail. `style` carries a palette's
+ * custom properties.
+ */
+export function PageBanner({ seed, picture, mark, className, style, children }) {
+    return (_jsxs("div", { className: className ? `page-banner ${className}` : 'page-banner', style: style, children: [picture ?? _jsx(BannerArt, { seed: seed, mark: mark }), children && _jsx("div", { className: "page-banner__body", children: children })] }));
+}

package/dist/base.css

@@ -463,6 +463,42 @@ tbody > tr:nth-child(even) > :is(th, td):not(.chart *) { background-image: linea
 }
 .breadcrumbs .separator { user-select: none; }
 
+/* ---- PageBanner and BannerArt -----------------------------------------------
+   4:1 is a floor, not a height: the ratio-holder and the body share one grid
+   cell, so the row is as tall as whichever needs more, and a long title on a
+   phone grows the banner rather than losing its trail off the top. The column
+   is minmax(0, 1fr), not auto, which would size to a long title's unwrapped
+   line. `max-height` caps only the picture, never the words. */
+.page-banner {
+  position: relative;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  overflow: hidden;
+  border-radius: var(--ui-radius);
+  background: var(--banner-field, var(--ui-surface));
+}
+.page-banner::before { content: ''; grid-area: 1 / 1; aspect-ratio: 4 / 1; max-height: 12rem; }
+.page-banner > :is(img, picture, svg) { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+/* `relative` only so it paints above the picture. */
+.page-banner__body {
+  grid-area: 1 / 1;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  min-width: 0;
+  padding: var(--ui-pad);
+}
+.page-banner__body > :is(h1, nav) { margin: 0; }
+.banner-art { display: block; width: 100%; height: 100%; }
+.banner-art__from { stop-color: var(--banner-from, transparent); }
+.banner-art__to { stop-color: var(--banner-to, transparent); }
+.banner-art__mid { fill: var(--banner-mid, var(--ui-muted)); }
+.banner-art__ink { fill: var(--banner-ink, var(--ui-accent)); }
+.banner-art__mid-line { fill: none; stroke: var(--banner-mid, var(--ui-muted)); }
+.banner-art__ink-line { fill: none; stroke: var(--banner-ink, var(--ui-accent)); }
+
 /* ---- Pager and SnapDots -----------------------------------------------------
    One line that never wraps, the count in tabular figures so stepping does not
    shift it. A step is a bare control: its colour, size and hit area are the

package/dist/mcp.d.ts

@@ -82,6 +82,8 @@ export type ToolSchema = {
  * calls has no way to tell a lookup from one that reaches a payment processor.
  */
 export type ToolAnnotations = {
+    /** The pre-2025-06-18 home of the label; `toolCard` mirrors `McpTool.title` here. */
+    title?: string;
     /** Does not modify anything. */
     readOnlyHint?: boolean;
     /** May destroy or overwrite state (only meaningful when not read-only). */
@@ -134,6 +136,10 @@ export interface McpTool {
  * One projection because the two copies drifted: the manifest's had no
  * `outputSchema`, so a descriptor said a tool answers with prose while
  * `tools/list` said it answers with `structuredContent`.
+ *
+ * The title goes out twice, top level and in `annotations`: clients and the
+ * Claude connectors directory that read only `annotations.title` otherwise
+ * report every tool untitled.
  */
 export declare function toolCard(tool: {
     name: string;

package/dist/mcp.js

@@ -75,6 +75,10 @@ import { clientKey, rateLimit, rateLimitHeaders, withRateLimit } from './rate-li
  * One projection because the two copies drifted: the manifest's had no
  * `outputSchema`, so a descriptor said a tool answers with prose while
  * `tools/list` said it answers with `structuredContent`.
+ *
+ * The title goes out twice, top level and in `annotations`: clients and the
+ * Claude connectors directory that read only `annotations.title` otherwise
+ * report every tool untitled.
  */
 export function toolCard(tool) {
     return {
@@ -83,7 +87,9 @@ export function toolCard(tool) {
         description: tool.description,
         inputSchema: tool.inputSchema,
         ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
-        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        ...(tool.annotations || tool.title
+            ? { annotations: { ...(tool.title ? { title: tool.title } : {}), ...tool.annotations } }
+            : {}),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -253,6 +253,11 @@
       "import": "./dist/seeded.js",
       "default": "./dist/seeded.js"
     },
+    "./banner": {
+      "types": "./dist/banner.d.ts",
+      "import": "./dist/banner.js",
+      "default": "./dist/banner.js"
+    },
     "./og": {
       "types": "./dist/og.d.ts",
       "import": "./dist/og.js",