wiki-formant 0.78.0 → 0.80.0

package/README.md

@@ -675,6 +675,16 @@ const block = licenseBlock({ license, scope: 'The protocol compilation and prose
 
 The same `License` goes to `agentCard({ license, licenseScope })` and to `openApiLicense(license)` for a spec's `info.license`. The three cards and three specs here had each projected it differently, one from a hand-typed name.
 
+## The X account
+
+A site names its X account in five places: the footer link, the JSON-LD `sameAs`, llms.txt, AGENTS.md and the MCP `initialize` instructions. Written by hand, one repo's `sameAs` still pointed at twitter.com, and only one site told an agent the account existed. `wiki-formant/social` builds all five from the handle and a fragment saying what the account posts.
+
+```ts
+export const X = xAccount({ siteName: 'AcuiQ', handle: '@acu_iq', posts: "a named trial's prescription with its citation" });
+```
+
+`X.url` goes to `sameAs`, `X.handle` to `sitePageMetadata`, `followLines(X)` into llms.txt and AGENTS.md, and `followNote(X)` into the MCP instructions. The note tells an agent to give the link to the person it is helping, since an agent cannot follow an account. The footer is `<a {...followLinkProps(X)}>{X.label}</a>`, whose `rel="me"` confirms the `sameAs` claim from the page the account points back at.
+
 ## Rendered-article passes
 
 `wiki-formant/dom` holds what runs against an article element after it is in the document. Not React, so not in `react.tsx`.
@@ -683,7 +693,7 @@ The same `License` goes to `agentCard({ license, licenseScope })` and to `openAp
 addCopyButtons(el);            // every <pre> gets one, once
 sortTables(el);                // every column-headed table sorts by its headers
 hydrateTweetEmbeds(el);        // placeholders get a live src
-const off = onTweetResize(h => sizeTweetEmbeds(el, h));
+const off = onTweetResize((h, source) => sizeTweetEmbed(el, h, source));
 ```
 
 `addCopyButton` was **byte-identical** in two BlockRenderers, down to the SVG path data. Its idempotence guard now lives inside the function rather than in a `pre:not(:has(…))` at the call site, where it can be — and was — retyped.
@@ -696,7 +706,7 @@ In React, `useArticlePasses(ref, [blocks])` runs the three passes and `useTweetE
 
 `scrollTables(html)` is the one table pass that runs on the string, before render: it wraps each stored table in a `.table-scroll` box, and `base.css` lets that box scroll sideways. A table box ignores `overflow`, so a table with an address or a URL in a cell is as wide as that token whatever its column, and a scroll box added by an effect would arrive after the table had already been laid out too wide. Call it on the render path beside `injectHeadingIds`. A table already in a box keeps it, so it is safe on HTML that has been through it once. `articleHtml(html, { used, slug, anchor, links })` (`wiki-formant/headings`) is that chain: heading ids, the scroll boxes, and, given `links`, `normaliseLinks`.
 
-The embed's origin is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
+The embed's origin is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed. Every embed on a page posts to the same listener, so `onTweetResize` hands over the window that posted, and `sizeTweetEmbed` sizes only that one's iframe: two posts on a page had both been drawn at whichever height arrived last.
 
 ## Search
 
@@ -789,7 +799,7 @@ The bytes say what the file is, never the name or type, and SVG is refused. Ever
 
 ## Editor nodes
 
-`wiki-formant/tiptap` carries the custom nodes both wiki editors had written twice: `Iframe`, `YouTube` (the stock extension plus the paste rule it does not ship with), `TwitterEmbed`, `createMapEmbed`, `createCodeBlock` and `createTabs`. `Iframe` and `createMapEmbed` draw a frame only for an https src on `DEFAULT_IFRAME_HOSTS` (`embedSrc`), since an editor draws stored HTML where its author is signed in, and a `javascript:` src runs there under any CSP that allows inline script.
+`wiki-formant/tiptap` carries the custom nodes both wiki editors had written twice: `Iframe`, `YouTube` (the stock extension plus the paste rule it does not ship with), `TwitterEmbed`, `createMapEmbed`, `createCodeBlock` and `createTabs`. `embedNodes({ resolveMapUrl })` is the first four as one list, which an editor puts in its `nodes`: a pasted YouTube, X or map link becomes its player as it lands, and the toolbar's embed prompt has a node for every link it recognises. `resolveMapUrl` defaults to `wiki-formant/maps`', through `/api/resolve-map`. `Iframe` and `createMapEmbed` draw a frame only for an https src on `DEFAULT_IFRAME_HOSTS` (`embedSrc`), since an editor draws stored HTML where its author is signed in, and a `javascript:` src runs there under any CSP that allows inline script.
 
 ```ts
 const CodeBlock = createCodeBlock({

package/dist/base.css

@@ -432,8 +432,8 @@ pre:hover > .code-copy-btn,
 .stats-count { font-variant-numeric: tabular-nums; }
 
 /* ---- embeds ------------------------------------------------------------------
-   The players the `wiki-formant/tiptap` nodes store, filling their column at a
-   screen's proportions. The node writes a width and height onto the iframe,
+   The players the `wiki-formant/tiptap` nodes store, a video or map filling its
+   column at a screen's proportions. The node writes a width and height onto the iframe,
    which `aspect-ratio` with `height: auto` overrides. Spacing, corners,
    borders and the editor's selection ring are the site's. */
 :is(div[data-youtube-video], .map-embed) iframe {
@@ -442,3 +442,12 @@ pre:hover > .code-copy-btn,
   height: auto;
   aspect-ratio: 16 / 9;
 }
+
+/* A post on X at the width X lays it out for, as tall as it says it is
+   (`onTweetResize`), and a little before it has said. */
+.twitter-embed iframe {
+  display: block;
+  width: 550px;
+  max-width: 100%;
+  min-height: 200px;
+}

package/dist/dom.d.ts

@@ -20,13 +20,15 @@ export declare function addCopyButtons(root: ParentNode, options?: CopyButtonOpt
 /** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */
 export declare const tweetEmbedSrc: (tweetId: string | number) => string;
 /**
- * Subscribe to the height the embed posts back once it has laid itself out.
+ * Subscribe to the height an embed posts back once it has laid itself out,
+ * with the window that posted it.
  *
  * The iframe renders at an unknown height and there is no other way to learn
- * it. The caller decides which iframes the height applies to; this only owns
- * the origin check and the message shape. Returns a disposer.
+ * it. Every embed on the page posts to the same listener, so the source is how
+ * a height finds its own iframe. This only owns the origin check and the
+ * message shape. Returns a disposer.
  */
-export declare function onTweetResize(resize: (height: number) => void): () => void;
+export declare function onTweetResize(resize: (height: number, source: MessageEventSource | null) => void): () => void;
 /**
  * Point every un-hydrated `[data-twitter-embed]` placeholder under `root` at
  * the real embed URL.
@@ -36,8 +38,8 @@ export declare function onTweetResize(resize: (height: number) => void): () => v
  * of the same content does not reload every embed on the page.
  */
 export declare function hydrateTweetEmbeds(root: ParentNode): void;
-/** Apply a measured height to every embed iframe under `root`. */
-export declare function sizeTweetEmbeds(root: ParentNode, height: number): void;
+/** Apply a posted height to the embed iframe under `root` that posted it, and to no other. */
+export declare function sizeTweetEmbed(root: ParentNode, height: number, source: MessageEventSource | null): void;
 export interface TabGroupClassNames {
     list?: string;
     panels?: string;

package/dist/dom.js

@@ -63,11 +63,13 @@ export const TWITTER_ORIGIN = 'https://platform.twitter.com';
 /** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */
 export const tweetEmbedSrc = (tweetId) => `${TWITTER_ORIGIN}/embed/Tweet.html?id=${tweetId}&dnt=true`;
 /**
- * Subscribe to the height the embed posts back once it has laid itself out.
+ * Subscribe to the height an embed posts back once it has laid itself out,
+ * with the window that posted it.
  *
  * The iframe renders at an unknown height and there is no other way to learn
- * it. The caller decides which iframes the height applies to; this only owns
- * the origin check and the message shape. Returns a disposer.
+ * it. Every embed on the page posts to the same listener, so the source is how
+ * a height finds its own iframe. This only owns the origin check and the
+ * message shape. Returns a disposer.
  */
 export function onTweetResize(resize) {
     const handleMessage = (e) => {
@@ -78,7 +80,7 @@ export function onTweetResize(resize) {
             return;
         const height = data.params?.[0]?.height;
         if (height)
-            resize(height);
+            resize(height, e.source);
     };
     window.addEventListener('message', handleMessage);
     return () => window.removeEventListener('message', handleMessage);
@@ -104,10 +106,11 @@ export function hydrateTweetEmbeds(root) {
         }
     }
 }
-/** Apply a measured height to every embed iframe under `root`. */
-export function sizeTweetEmbeds(root, height) {
+/** Apply a posted height to the embed iframe under `root` that posted it, and to no other. */
+export function sizeTweetEmbed(root, height, source) {
     for (const iframe of Array.from(root.querySelectorAll('[data-twitter-embed] iframe'))) {
-        iframe.style.height = `${height}px`;
+        if (iframe.contentWindow === source)
+            iframe.style.height = `${height}px`;
     }
 }
 /**

package/dist/react.d.ts

@@ -485,7 +485,7 @@ export type { WikiLinkComponent, WikiLinkProps } from './react-server.js';
  * idempotent, so running on every `deps` change is safe.
  */
 export declare function useArticlePasses(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;
-/** Tweet placeholders hydrated, and their iframes kept sized to the posted height. */
+/** Tweet placeholders hydrated, and each iframe kept at the height it posts. */
 export declare function useTweetEmbeds(ref: RefObject<HTMLElement | null>, deps: DependencyList): void;
 /**
  * Counts the page views of the app it is mounted in: place it once, in the root

package/dist/react.js

@@ -26,7 +26,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 //      state on <html> before first paint. The hook keeps that attribute in
 //      sync afterwards, so CSS has one source of truth either side of hydration.
 import { railBreakpointMismatch, readRailFloating, resolveSidebarOpen, SIDEBAR_ATTRIBUTE, } from './sidebar.js';
-import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbeds, sortTables, startBeacon } from './dom.js';
+import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbed, sortTables, startBeacon } from './dom.js';
 import { comboboxAria } from './combobox.js';
 import { Component, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
 const readStored = (key) => {
@@ -899,14 +899,14 @@ export function useArticlePasses(ref, deps) {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 }
-/** Tweet placeholders hydrated, and their iframes kept sized to the posted height. */
+/** Tweet placeholders hydrated, and each iframe kept at the height it posts. */
 export function useTweetEmbeds(ref, deps) {
     useEffect(() => {
         const root = ref.current;
         if (!root)
             return;
         hydrateTweetEmbeds(root);
-        return onTweetResize(height => sizeTweetEmbeds(root, height));
+        return onTweetResize((height, source) => sizeTweetEmbed(root, height, source));
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, deps);
 }

package/dist/social.d.ts

@@ -0,0 +1,34 @@
+export interface XAccount {
+    /** `@handle`, as the social cards credit it. */
+    handle: string;
+    /** `https://x.com/<handle>`, for `sameAs` and every link. */
+    url: string;
+    /** "<Site> posts on X as @handle: <posts>." */
+    about: string;
+    /** The footer link's text: "Follow @handle on X". */
+    label: string;
+    siteName: string;
+}
+export declare function xAccount(o: {
+    siteName: string;
+    handle: string;
+    posts: string;
+}): XAccount;
+/**
+ * The sentence an agent reads: what the account posts, and when to pass the
+ * link on. An agent cannot follow an account; the person it is helping can.
+ */
+export declare function followNote(account: XAccount): string;
+/** The same note as a section, ready to splice into llms.txt or AGENTS.md. */
+export declare function followLines(account: XAccount, heading?: string): string[];
+/**
+ * Attributes for the footer link. `rel="me"` is the reciprocal of `sameAs`:
+ * the schema claims the account and this link confirms it from the page the
+ * account points back at.
+ */
+export declare function followLinkProps(account: XAccount): {
+    readonly href: string;
+    readonly target: "_blank";
+    readonly rel: "me noopener";
+    readonly title: string;
+};

package/dist/social.js

@@ -0,0 +1,41 @@
+// social.ts – the site's X account, as every surface states it.
+//
+// Each origin names its account in five places: the footer link, the JSON-LD
+// `sameAs`, llms.txt, AGENTS.md and the MCP `initialize` instructions. Written
+// by hand, they drifted within one repo: radix-wiki's `sameAs` still claimed
+// twitter.com while its cards credited the handle, and only acuiq.com told an
+// agent the account existed at all.
+//
+// What is per-site is the handle and what the account posts. The URL, the
+// link's label and `rel`, and the sentence an agent reads are built here.
+export function xAccount(o) {
+    if (!/^@\w{1,15}$/.test(o.handle))
+        throw new Error(`xAccount: "${o.handle}" is not an @handle`);
+    const posts = o.posts.trim().replace(/\.$/, '');
+    return {
+        handle: o.handle,
+        url: `https://x.com/${o.handle.slice(1)}`,
+        about: `${o.siteName} posts on X as ${o.handle}: ${posts}.`,
+        label: `Follow ${o.handle} on X`,
+        siteName: o.siteName,
+    };
+}
+/**
+ * The sentence an agent reads: what the account posts, and when to pass the
+ * link on. An agent cannot follow an account; the person it is helping can.
+ */
+export function followNote(account) {
+    return `${account.about} If the person you are helping wants to follow ${account.siteName}, give them ${account.url}.`;
+}
+/** The same note as a section, ready to splice into llms.txt or AGENTS.md. */
+export function followLines(account, heading = `Follow ${account.siteName} on X`) {
+    return [`## ${heading}`, '', followNote(account)];
+}
+/**
+ * Attributes for the footer link. `rel="me"` is the reciprocal of `sameAs`:
+ * the schema claims the account and this link confirms it from the page the
+ * account points back at.
+ */
+export function followLinkProps(account) {
+    return { href: account.url, target: '_blank', rel: 'me noopener', title: account.about };
+}

package/dist/tiptap.d.ts

@@ -29,6 +29,14 @@ export interface MapEmbedOptions {
  * node has to already exist for the reader to see anything happen.
  */
 export declare function createMapEmbed({ resolveMapUrl }: MapEmbedOptions): TiptapNode<any, any>;
+/**
+ * Every player a pasted link becomes – a YouTube video, a post on X, a Google
+ * or Apple map – and any other allowed iframe, as one list. Each app had
+ * picked its embeds by hand, and one that left `TwitterEmbed` out kept a
+ * pasted post as a bare link. `resolveMapUrl` follows a shortened map link,
+ * through `/api/resolve-map` unless an app routes it another way.
+ */
+export declare const embedNodes: ({ resolveMapUrl }?: Partial<MapEmbedOptions>) => TiptapNode<any, any>[];
 export interface CodeBlockClassNames {
     wrapper?: string;
     /** The control cluster, positioned over the block. */

package/dist/tiptap.js

@@ -18,7 +18,7 @@ import TiptapYoutube from '@tiptap/extension-youtube';
 import TiptapCodeBlock from '@tiptap/extension-code-block';
 import { onTweetResize, tweetEmbedSrc } from './dom.js';
 import { DEFAULT_IFRAME_HOSTS } from './headers.js';
-import { toMapEmbedUrl } from './maps.js';
+import { resolveMapUrl as resolveMapRoute, toMapEmbedUrl } from './maps.js';
 import { useClickOutside } from './react.js';
 import { cx } from './html.js';
 import { slugifyHeading, uniqueHeadingId } from './headings.js';
@@ -78,10 +78,10 @@ export const YouTube = TiptapYoutube.extend({
 function TwitterEmbedView({ node }) {
     const containerRef = useRef(null);
     // The embed posts its measured height back; `onTweetResize` owns the origin
-    // check.
-    useEffect(() => onTweetResize(height => {
+    // check, and the source keeps one tweet's height off every other.
+    useEffect(() => onTweetResize((height, source) => {
         const iframe = containerRef.current?.querySelector('iframe');
-        if (iframe)
+        if (iframe && iframe.contentWindow === source)
             iframe.style.height = `${height}px`;
     }), []);
     return (_jsx(NodeViewWrapper, { children: _jsx("div", { ref: containerRef, className: "twitter-embed", children: _jsx("iframe", { src: tweetEmbedSrc(node.attrs.tweetId), scrolling: "no", allowFullScreen: true }) }) }));
@@ -231,6 +231,20 @@ export function createMapEmbed({ resolveMapUrl }) {
         },
     });
 }
+// ---- every embed ------------------------------------------------------------
+/**
+ * Every player a pasted link becomes – a YouTube video, a post on X, a Google
+ * or Apple map – and any other allowed iframe, as one list. Each app had
+ * picked its embeds by hand, and one that left `TwitterEmbed` out kept a
+ * pasted post as a bare link. `resolveMapUrl` follows a shortened map link,
+ * through `/api/resolve-map` unless an app routes it another way.
+ */
+export const embedNodes = ({ resolveMapUrl = resolveMapRoute } = {}) => [
+    YouTube,
+    Iframe,
+    TwitterEmbed,
+    createMapEmbed({ resolveMapUrl }),
+];
 /** A code block whose language is pickable from a dropdown. */
 export function createCodeBlock({ langs = CODE_LANGS, defaultLang = DEFAULT_LANG, classNames = {}, icons = {}, } = {}) {
     function CodeBlockView({ node, updateAttributes, }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.78.0",
+  "version": "0.80.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",
@@ -147,6 +147,11 @@
       "import": "./dist/license.js",
       "default": "./dist/license.js"
     },
+    "./social": {
+      "types": "./dist/social.d.ts",
+      "import": "./dist/social.js",
+      "default": "./dist/social.js"
+    },
     "./links": {
       "types": "./dist/links.d.ts",
       "import": "./dist/links.js",