@supersuit/artifacts 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.39.0
+
+**A session demo's frame fits its player, and is wider than the reading column on a wide screen.**
+A ```` ```simulator ```` block drew its player in a frame of one fixed height (`height:`, 720px
+unless the block said). A session demo draws a different device for each viewer, a short laptop on
+a desktop and a tall phone on a phone, so one height suited neither: on a desktop a band of
+nothing, some 300px, sat between the laptop and the caption.
+
+- The frame now asks its embed page `fit=content` (the address gains `&fit=content`), and a page
+  that understands posts `{ type: 'embed:fit', height: <px> }` to its parent. The frame takes that
+  height (`EmbedFrame`, a client component; `fitFrom`, `FIT_MESSAGE`): only that message, only from
+  the frame's own window and the origin of the page it loaded, held between 240 and 2000px.
+- `height:` still means what it meant: the height the frame opens at, and so the room the player is
+  given. A page that posts nothing keeps it. No published page needs a change.
+- From 1024px a framed session demo is up to 64rem wide, centred on the column and clear of the
+  contents rail in the left margin from 1280px, with its caption centred under it. In a broadcast's
+  card, below 1024px, for the Messages phone, and for a caption with no player, the column is the
+  width, as before.
+
+DETECTOR: open a page with a ```` ```simulator ```` block on a desktop. Affected: the frame is the
+block's height whatever the device in it, with empty space under a laptop. Or
+`curl -s <page> | grep -o 'simulator/embed[^"]*'` shows no `fit=content`.
+
+REMEDY: take 0.39.0. A host whose embed page is not its own does nothing more: an unknown query key
+is ignored and the frame keeps the block's height. A host that serves its own embed page makes it
+answer `fit=content` in two steps, in this order: hold the player at the height the frame opened
+with (inside a frame the viewport IS the frame, so a player sized from it shrinks as the frame
+does and the two chase each other), then post its content's height as `embed:fit` whenever it
+changes. Centre the player in the frame as well, for hosts that never listen.
+
+Tests: `simulator.test.ts` (the address asks to fit and the Messages one does not; `fitFrom` takes
+the message from the right origin, refuses every other shape, and clamps), `embed-frame.test.tsx`
+(the frame opens at the block's height, takes a reported one, and ignores another window, origin
+and message), `render.test.tsx` (the opening height with and without `height:`; the wide rule is on
+a framed session demo only, never the Messages phone or a caption with no player). The wide rule
+itself is CSS and is not run by a test here: it was checked in a browser at 390, 1100 and 1440px.
+
 ## 0.38.0
 
 **Readers' voice memos live in the private bucket.** A memo left on a page (`comments/<memo>`, or a

package/lib/artifacts/embed-frame.d.ts

@@ -0,0 +1,5 @@
+export declare function EmbedFrame({ src, title, height }: {
+    src: string;
+    title: string;
+    height: string;
+}): import("react").JSX.Element;

package/lib/artifacts/embed-frame.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+// The frame an embed block plays in. It opens at the block's height and, when its embed page
+// reports how tall the player is (simulator.ts, "A frame that fits"), takes that height, so a
+// short device has no empty band under it and a tall one is not cut off.
+import { useEffect, useRef, useState } from 'react';
+import { fitFrom } from './simulator.js';
+export function EmbedFrame({ src, title, height }) {
+    const ref = useRef(null);
+    const [fit, setFit] = useState(null);
+    useEffect(() => {
+        const onMessage = (e) => {
+            if (!ref.current || e.source !== ref.current.contentWindow)
+                return;
+            const h = fitFrom(e.data, e.origin, src);
+            if (h != null)
+                setFit(h);
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }, [src]);
+    return (_jsx("iframe", { ref: ref, src: src, title: title, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: fit != null ? `${fit}px` : height, border: 0 } }));
+}

package/lib/artifacts/index.d.ts

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
 export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
 export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS, type ResolveEvent, type DigestItem, type Burst, type Digest, type DigestStatus, type ResolveDigestStore, type DigestMessage, type DigestSender, type ResolveDigestOptions, type ComposeOptions, type FlushReport } from './resolve-digest.js';

package/lib/artifacts/index.js

@@ -13,7 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
-export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS } from './simulator.js';
+export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
 export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS } from './resolve-digest.js';

package/lib/artifacts/render.js

@@ -17,6 +17,7 @@ import { blocksOf, checklistSyncs, checklistsOf, hasNotesWidget, headingsOf } fr
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { Checklist } from '../widgets/checklist.js';
 import { embedSrc, parseEmbedFence } from './simulator.js';
+import { EmbedFrame } from './embed-frame.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -110,6 +111,17 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio data-artifact-media="${escapeAttr(mediaName(src))}" controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
+// A session demo on a wide screen is wider than the reading column, so the device it draws (a
+// laptop, or a phone beside what was made) has room: up to 64rem, centred on the column, and clear
+// of the contents rail fixed in the left margin from 1280px (w-56 at left-6, w-64 at left-12).
+// Below 1024px, in a broadcast's card, for the Messages phone, and for a caption with no player
+// over it (a host that names no embed page), the column is the width.
+const WIDE = '[data-artifact-embed="simulator"][data-wide]';
+const WIDE_EMBED_CSS = `@media (min-width:1024px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 4rem)));margin-left:50%;transform:translateX(-50%)}` +
+    `${WIDE} figcaption{text-align:center}` +
+    `[data-broadcast] ${WIDE}{width:auto;margin-left:0;transform:none}[data-broadcast] ${WIDE} figcaption{text-align:inherit}}` +
+    `@media (min-width:1280px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 36rem)))}}` +
+    `@media (min-width:1536px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 40rem)))}}`;
 /** An embed block (```simulator, ```messages): the player in a frame when the host names one, its
  *  caption alone when it does not, and nothing when the block does not parse (a page published
  *  before validation existed). */
@@ -118,7 +130,8 @@ function EmbedFence({ kind, source, ctx }) {
     if (!r.ok)
         return null;
     const src = ctx ? embedSrc(kind, ctx.embed, r.block.value) : null;
-    return (_jsxs("figure", { "data-artifact-embed": kind, ...(kind === 'simulator' ? { 'data-artifact-simulator': '' } : {}), className: "my-8", children: [src ? (_jsx("iframe", { src: src, title: r.block.caption, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: r.block.height, border: 0 } })) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
+    const wide = kind === 'simulator' && src != null;
+    return (_jsxs("figure", { "data-artifact-embed": kind, ...(kind === 'simulator' ? { 'data-artifact-simulator': '' } : {}), ...(wide ? { 'data-wide': '' } : {}), className: "my-8", children: [wide ? _jsx("style", { children: WIDE_EMBED_CSS }) : null, src ? _jsx(EmbedFrame, { src: src, title: r.block.caption, height: r.block.height }) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
 }
 /** The one image a paragraph holds and nothing else (whitespace aside), or null. */
 function soleImage(node) {

package/lib/artifacts/simulator.d.ts

@@ -32,3 +32,10 @@ export declare function parseSimulatorFence(value: string, line: number): {
     error: string;
 };
 export declare const simulatorSrc: (embed: string, scenario: string) => string | null;
+/** The message an embed page sends its frame, and the heights a frame will take. */
+export declare const FIT_MESSAGE = "embed:fit";
+export declare const FIT_MIN = 240;
+export declare const FIT_MAX = 2000;
+/** The height (px) a frame takes from a message, or null: only `embed:fit` with a finite number,
+ *  only from the origin of the page the frame loaded, and never outside FIT_MIN..FIT_MAX. */
+export declare function fitFrom(data: unknown, origin: string, src: string): number | null;

package/lib/artifacts/simulator.js

@@ -11,8 +11,16 @@
 // (ArtifactRoutesConfig.simulatorEmbed / messagesEmbed), so this public package points at nobody's
 // service by default, and a host without the player draws the caption alone rather than the block's
 // source as code. `simulator` keeps the syntax the Superskills book's reader takes.
+//
+// A FRAME THAT FITS (0.39.0). `height:` is the height a frame OPENS at, and the room its player is
+// given. A session demo draws a different device for each viewer (a short laptop on a desktop, a
+// tall phone on a phone), so no one height suits both: the frame asked its embed page `fit=content`,
+// and a page that understands posts `{ type: 'embed:fit', height: <px> }` to its parent, which the
+// frame then takes (EmbedFrame). A page that posts nothing keeps the block's height. The embed
+// page must hold its player's size once asked, never size it from its own viewport, or the two
+// chase each other; that is why the frame listens only for this message and for no player's own.
 const KINDS = {
-    simulator: { key: 'scenario', required: true, fixed: { timeline: 'off' }, height: '720px' },
+    simulator: { key: 'scenario', required: true, fixed: { timeline: 'off', fit: 'content' }, height: '720px' },
     messages: { key: 'chat', required: false, fixed: {}, height: '760px' },
 };
 export const EMBED_KINDS = Object.keys(KINDS);
@@ -74,3 +82,26 @@ export function parseSimulatorFence(value, line) {
     return r.ok ? { ok: true, block: { scenario: r.block.value, caption: r.block.caption, height: r.block.height } } : r;
 }
 export const simulatorSrc = (embed, scenario) => embedSrc('simulator', embed, scenario);
+/** The message an embed page sends its frame, and the heights a frame will take. */
+export const FIT_MESSAGE = 'embed:fit';
+export const FIT_MIN = 240;
+export const FIT_MAX = 2000;
+/** The height (px) a frame takes from a message, or null: only `embed:fit` with a finite number,
+ *  only from the origin of the page the frame loaded, and never outside FIT_MIN..FIT_MAX. */
+export function fitFrom(data, origin, src) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const d = data;
+    if (d.type !== FIT_MESSAGE || typeof d.height !== 'number' || !Number.isFinite(d.height))
+        return null;
+    let expected;
+    try {
+        expected = new URL(src).origin;
+    }
+    catch {
+        return null;
+    }
+    if (origin !== expected)
+        return null;
+    return Math.max(FIT_MIN, Math.min(FIT_MAX, Math.ceil(d.height)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",