@konvert7/promoot 0.2.1 → 0.4.0

package/README.md

@@ -16,6 +16,26 @@ import { PromootBlock } from "@konvert7/promoot";
 The `url` is the embed URL from your Promoot dashboard — the same string the iframe
 snippet uses, so one value serves either method.
 
+## What it renders
+
+Whatever the sponsor bought, without you choosing:
+
+- **An image ad** — their artwork, cropped to fill the slot.
+- **A text ad** — their favicon, a headline, a description and their domain, centred.
+  Headline and description are both optional; a link on its own renders the mark and
+  the bare domain. If no favicon could be captured, a monogram of the domain's first
+  letter is shown instead — never both, so a transparent icon can't show the letter
+  through it.
+
+And when nobody has bought it yet, the slot sells itself. If the owner composed an empty
+state in their dashboard, it renders as a billboard: the lines they chose — their own
+words, the price, the view count, their domain — over a faint chart of the last 30 days
+of traffic, with a preview of the visitor's own ad fading in on hover. Owners who never
+composed one get the plain pitch instead: headline, audience, proof and terms.
+
+The empty state needs no configuration here. It arrives resolved from the server, so the
+words are already the words, and this block only sets them.
+
 ## Why inline
 
 An iframe fails closed. If a content filter ever blocks the frame, your sponsor's ad
@@ -68,7 +88,9 @@ visitor's browser fetches regardless of how that HTML was produced.
 The block **never declares a colour scheme of its own**. Its palette uses `light-dark()`,
 which resolves against the scheme it inherits from your page — so a light-only site keeps
 a light panel even for a visitor whose OS prefers dark, and a dark site gets a dark one.
-All of its CSS is scoped to the block; nothing is defined on `:root`.
+All of its CSS is scoped to the block; nothing is defined on `:root`. The only name it
+declares globally is the keyframes the empty state breathes with on touch devices, and
+that name carries the slot's own id, so two blocks on one page never collide.
 
 The one thing you cannot restyle is the "Sponsored" label, which renders from inline
 styles. Disclosure of a paid placement is not the site owner's to remove.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { PromootBlock, type PromootBlockProps } from "./promoot-block.js";
-export type { BlockPayload, BlockRender } from "./types.js";
+export type { BlockPayload, BlockRender, Creative, PitchLine } from "./types.js";

package/dist/promoot-block.js

@@ -1,4 +1,4 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 export function blockEndpoint(embedUrl) {
     return embedUrl.replace("/embed/", "/api/block/");
 }
@@ -16,19 +16,60 @@ async function loadBlock(embedUrl) {
 // Every rule is scoped to this one block, and it never declares a colour scheme
 // of its own: the palette uses light-dark(), which resolves against the scheme
 // inherited from the host page, so a light-only site keeps a light panel.
+// A keyframe name cannot be scoped to a selector, so it carries the slot's own
+// id instead, stripped to the characters a css identifier may hold.
+function breatheName(slotId, face) {
+    return `promoot-breathe-${face}-${slotId.replaceAll(/[^A-Za-z0-9_-]/g, "")}`;
+}
+const mono = "ui-monospace, SFMono-Regular, Menlo, monospace";
+// The face the owner composed, and the ghost that shows a visitor what their own
+// ad would look like in its place. Both are stacked, and hover swaps them.
+function billboardCss(payload, scope) {
+    const rest = breatheName(payload.slot.id, "rest");
+    const ghost = breatheName(payload.slot.id, "ghost");
+    return `${scope} .promoot-bb { position: relative; display: block; width: 100%; height: 100%; box-sizing: border-box; border: 1px solid var(--edge); border-radius: 10px; background: var(--surface); overflow: hidden; font-family: system-ui, -apple-system, sans-serif; }
+${scope} .promoot-bb:hover { border-color: var(--edge-hover); }
+${scope} .promoot-face { position: absolute; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 4px; padding: 10px 16px; box-sizing: border-box; text-align: center; transition: opacity .3s ease; }
+${scope} .promoot-bb:hover .promoot-rest { opacity: 0; }
+${scope} .promoot-ghost { flex-direction: row; gap: 12px; text-align: left; opacity: 0; }
+${scope} .promoot-bb:hover .promoot-ghost { opacity: 1; }
+${scope} .promoot-spark { position: absolute; left: 0; right: 0; bottom: 0; width: 100%; height: 34%; pointer-events: none; }
+${scope} .promoot-spark polygon { fill: var(--surface-hover); }
+${scope} .promoot-spark polyline { fill: none; stroke: var(--edge); stroke-width: 1.5; }
+${scope} .promoot-line { position: relative; max-width: 100%; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+${scope} .promoot-line-text { font-size: 15px; font-weight: 600; color: var(--ink); }
+${scope} .promoot-line-price { font-family: ${mono}; font-size: 12.5px; font-weight: 600; color: var(--ink); }
+${scope} .promoot-line-proof, ${scope} .promoot-line-domain { font-family: ${mono}; font-size: 11px; color: var(--muted); }
+${scope} .promoot-plus { flex: none; display: grid; place-items: center; width: 36px; height: 36px; border-radius: 9px; border: 1.5px dashed var(--muted); color: var(--muted); font-size: 18px; }
+${scope} .promoot-ghost-title { display: block; font-size: 13.5px; font-weight: 600; color: var(--ink); }
+${scope} .promoot-ghost-body { display: block; font-size: 12px; color: var(--muted); }
+@media (hover: none) { ${scope} .promoot-rest { animation: ${rest} 12s ease-in-out 2s infinite; } ${scope} .promoot-ghost { animation: ${ghost} 12s ease-in-out 2s infinite; } }
+@media (prefers-reduced-motion: reduce) { ${scope} .promoot-rest, ${scope} .promoot-ghost { animation: none; } ${scope} .promoot-face { transition: none; } }
+@keyframes ${rest} { 0%, 55%, 100% { opacity: 1; } 70%, 85% { opacity: 0; } }
+@keyframes ${ghost} { 0%, 55%, 100% { opacity: 0; } 70%, 85% { opacity: 1; } }`;
+}
 export function scopedCss(payload) {
     const scope = `[data-promoot-slot="${payload.slot.id}"]`;
     return `${scope} { ${payload.paletteVars}; position: relative; display: block; width: 100%; max-width: ${payload.slot.widthPx}px; height: auto; max-height: ${payload.slot.heightPx}px; aspect-ratio: ${payload.slot.widthPx} / ${payload.slot.heightPx}; }
 ${scope} a { text-decoration: none; }
 ${scope} .promoot-ad { display: block; position: relative; height: 100%; width: 100%; }
-${scope} .promoot-ad img { display: block; height: 100%; width: 100%; object-fit: cover; }
+${scope} .promoot-ad > img { display: block; height: 100%; width: 100%; object-fit: cover; }
+${scope} .promoot-text { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 3px; width: 100%; height: 100%; box-sizing: border-box; padding: 6px 12px; border: 1px solid var(--edge); border-radius: 10px; background: var(--surface); overflow: hidden; text-align: center; font-family: system-ui, -apple-system, sans-serif; }
+${scope} .promoot-ad:hover .promoot-text { border-color: var(--edge-hover); background: var(--surface-hover); }
+${scope} .promoot-mark { position: relative; flex: none; display: grid; place-items: center; width: 24px; height: 24px; margin-bottom: 1px; border-radius: 6px; background: var(--edge); color: var(--surface); font-weight: 700; font-size: 12px; overflow: hidden; }
+${scope} .promoot-mark img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; }
+${scope} .promoot-text > span:not(.promoot-mark) { max-width: 100%; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+${scope} .promoot-text .promoot-headline { font-size: 14px; font-weight: 600; color: var(--ink); line-height: 1.25; }
+${scope} .promoot-text .promoot-desc { font-size: 12px; color: var(--muted); line-height: 1.25; }
+${scope} .promoot-text .promoot-host { font-size: 11px; color: var(--muted); line-height: 1.25; }
 ${scope} .promoot-cta { display: flex; flex-direction: column; align-items: center; gap: 3px; width: 100%; height: 100%; justify-content: center; padding: 0 10px; text-align: center; border: 1px dashed var(--edge); border-radius: 10px; box-sizing: border-box; color: var(--muted); background: var(--surface); font-family: system-ui, -apple-system, sans-serif; }
 ${scope} .promoot-cta:hover { border-color: var(--edge-hover); background: var(--surface-hover); }
 ${scope} .promoot-cta strong { font-size: 14px; color: var(--ink); }
 ${scope} .promoot-cta .promoot-pitch { font-size: 13px; color: var(--ink); }
 ${scope} .promoot-cta .promoot-proof { font-size: 11px; color: var(--muted); }
 ${scope} .promoot-cta .promoot-terms { font-size: 12px; }
-${scope} .promoot-beacon { position: absolute; bottom: 0; right: 0; width: 1px; height: 1px; }`;
+${scope} .promoot-beacon { position: absolute; bottom: 0; right: 0; width: 1px; height: 1px; }
+${billboardCss(payload, scope)}`;
 }
 // Inline, not a class: a host can restyle everything else, but the disclosure
 // is not theirs to remove.
@@ -43,10 +84,52 @@ const labelStyle = {
     borderRadius: "4px",
     padding: "1px 5px",
 };
+// One or the other, never layered: a favicon with transparent corners would let
+// the monogram show through it, and a broken image painted over the letter
+// hides it anyway.
+function Mark({ creative }) {
+    return (_jsx("span", { className: "promoot-mark", children: creative.faviconUrl ? (_jsx("img", { src: creative.faviconUrl, alt: "" })) : (creative.monogram) }));
+}
+function AdCreative({ creative }) {
+    if (creative.kind === "IMAGE") {
+        return _jsx("img", { src: creative.imageUrl, alt: creative.title });
+    }
+    return (_jsxs("span", { className: "promoot-text", children: [_jsx(Mark, { creative: creative }), creative.headline && _jsx("span", { className: "promoot-headline", children: creative.headline }), creative.body && _jsx("span", { className: "promoot-desc", children: creative.body }), _jsx("span", { className: "promoot-host", children: creative.host })] }));
+}
+// Oldest day first across a fixed box, which the slot's own aspect ratio then
+// stretches: one path serves every size.
+function sparkPoints(series) {
+    const max = Math.max(...series, 1);
+    const step = series.length > 1 ? 600 / (series.length - 1) : 600;
+    return series
+        .map((value, index) => {
+        const x = Math.round(index * step * 10) / 10;
+        const y = Math.round((44 - (value / max) * 38) * 10) / 10;
+        return `${x},${y}`;
+    })
+        .join(" ");
+}
+function Spark({ series }) {
+    const points = sparkPoints(series);
+    return (_jsxs("svg", { className: "promoot-spark", viewBox: "0 0 600 48", preserveAspectRatio: "none", "aria-hidden": "true", children: [_jsx("polygon", { points: `0,48 ${points} 600,48` }), _jsx("polyline", { points: points })] }));
+}
+// What the owner wrote, with a preview of somebody else's ad underneath it: the
+// empty slot sells itself to the visitor who could fill it.
+function Billboard({ pitch, lines }) {
+    return (_jsxs("a", { className: "promoot-bb", href: pitch.purchaseUrl, target: "_blank", rel: "noopener", children: [_jsxs("span", { className: "promoot-face promoot-rest", children: [pitch.spark?.length ? _jsx(Spark, { series: pitch.spark }) : null, lines.map((line, index) => (_jsx("span", { className: `promoot-line promoot-line-${line.kind}`, children: line.text }, `${line.kind}-${index}`)))] }), _jsxs("span", { className: "promoot-face promoot-ghost", children: [_jsx("span", { className: "promoot-plus", children: "+" }), _jsxs("span", { children: [_jsx("span", { className: "promoot-ghost-title", children: "Your product \u00B7 one line your buyers read" }), _jsxs("span", { className: "promoot-ghost-body", children: ["This is how it would look.", pitch.price ? ` ${pitch.price}.` : ""] })] })] })] }));
+}
+function ClassicPitch({ pitch }) {
+    return (_jsxs("a", { className: "promoot-cta", href: pitch.purchaseUrl, target: "_blank", rel: "noopener", children: [_jsx("strong", { children: pitch.headline }), pitch.pitch && _jsx("span", { className: "promoot-pitch", children: pitch.pitch }), pitch.proof && _jsx("span", { className: "promoot-proof", children: pitch.proof }), _jsx("span", { className: "promoot-terms", children: pitch.terms })] }));
+}
+// A server that has not learned to compose an empty state sends no lines, and
+// the pitch it does send is rendered exactly as it always was.
+function EmptySlot({ pitch }) {
+    return pitch.lines?.length ? (_jsx(Billboard, { pitch: pitch, lines: pitch.lines })) : (_jsx(ClassicPitch, { pitch: pitch }));
+}
 export async function PromootBlock({ url, className, style, fallback = null, }) {
     const block = await loadBlock(url);
     if (!block || block.render === "blank") {
         return _jsx(_Fragment, { children: fallback });
     }
-    return (_jsxs("div", { "data-promoot-slot": block.slot.id, className: className, style: style, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: scopedCss(block) } }), block.ad && (_jsxs("a", { className: "promoot-ad", href: block.ad.clickUrl, target: "_blank", rel: "noopener nofollow sponsored", children: [_jsx("img", { src: block.ad.imageUrl, alt: block.ad.title }), block.slot.sponsoredLabel && (_jsx("span", { style: labelStyle, children: block.slot.sponsoredLabel }))] })), block.pitch && (_jsxs("a", { className: "promoot-cta", href: block.pitch.purchaseUrl, target: "_blank", rel: "noopener", children: [_jsx("strong", { children: block.pitch.headline }), block.pitch.pitch && _jsx("span", { className: "promoot-pitch", children: block.pitch.pitch }), block.pitch.proof && _jsx("span", { className: "promoot-proof", children: block.pitch.proof }), _jsx("span", { className: "promoot-terms", children: block.pitch.terms })] })), _jsx("img", { className: "promoot-beacon", src: block.beaconUrl, width: 1, height: 1, alt: "", "aria-hidden": "true" })] }));
+    return (_jsxs("div", { "data-promoot-slot": block.slot.id, className: className, style: style, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: scopedCss(block) } }), block.ad && (_jsxs("a", { className: "promoot-ad", href: block.ad.clickUrl, target: "_blank", rel: "noopener nofollow sponsored", children: [_jsx(AdCreative, { creative: block.ad }), block.slot.sponsoredLabel && (_jsx("span", { style: labelStyle, children: block.slot.sponsoredLabel }))] })), block.pitch && _jsx(EmptySlot, { pitch: block.pitch }), _jsx("img", { className: "promoot-beacon", src: block.beaconUrl, width: 1, height: 1, alt: "", "aria-hidden": "true" })] }));
 }

package/dist/types.d.ts

@@ -1,4 +1,27 @@
 export type BlockRender = "ad" | "pitch" | "blank";
+/** An ad is either artwork the sponsor uploaded, or words they wrote. */
+export type Creative = {
+    kind: "IMAGE";
+    title: string;
+    imageUrl: string;
+} | {
+    kind: "TEXT";
+    /** Optional: a link alone is a complete ad, and the host stands in. */
+    headline: string | null;
+    body: string | null;
+    /** Null when the sponsor's site has none, or it could not be captured. */
+    faviconUrl: string | null;
+    host: string;
+    monogram: string;
+};
+/**
+ * One line of the empty state the slot's owner composed, already resolved into
+ * the words it prints. The kind only decides how it is set.
+ */
+export type PitchLine = {
+    kind: "text" | "price" | "proof" | "domain";
+    text: string;
+};
 /** What GET /api/block/:slotId answers with. */
 export type BlockPayload = {
     slot: {
@@ -8,18 +31,25 @@ export type BlockPayload = {
         sponsoredLabel: string | null;
     };
     render: BlockRender;
-    ad: {
-        title: string;
-        imageUrl: string;
+    ad: ({
         clickUrl: string;
         expiresAt: string | null;
-    } | null;
+    } & Creative) | null;
     pitch: {
         headline: string;
         pitch: string | null;
         proof: string | null;
         terms: string;
         purchaseUrl: string;
+        /**
+         * The owner's composed empty state. Present from Promoot 0.4 onwards; an
+         * older server omits it and the classic pitch is rendered instead.
+         */
+        lines?: PitchLine[] | null;
+        /** Daily views behind the lines, already gated by the owner's traffic floor. */
+        spark?: number[] | null;
+        /** The price on its own, formatted. */
+        price?: string;
     } | null;
     beaconUrl: string;
     paletteVars: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/promoot",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Render a Promoot sponsor slot inline as a React server component, with views counted by the visitor's own browser.",
   "type": "module",
   "main": "./dist/index.js",