@supersuit/artifacts 0.37.0 → 0.39.0

package/CHANGELOG.md

@@ -3,6 +3,66 @@
 `@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
+reader's own `personal/<dir>/<memo>`) was written to the PUBLIC bucket. Every URL the package handed
+out was signed, but that bucket carries a bucket-wide public read grant, so the memo itself answered
+an unsigned GET to anyone holding its path. Memos are now written to and read from the private
+bucket (`privateBucket`), under the same key. A host with no private bucket defines no memo method,
+so memos stay on the reader's device instead of going anywhere public.
+
+DETECTOR: an unsigned `curl -o /dev/null -w '%{http_code}'` of
+`https://storage.googleapis.com/<public bucket>/<prefix>/<id>/comments/<memo>.webm` answers 200.
+
+REMEDY: take 0.38.0, then move what is already there:
+`node scripts/migrate-memos-private.mjs --public <bucket> --private <bucket> --prefix tenants/<t>/artifacts`
+(copies each memo to the same key in the private bucket, confirms it arrived, then deletes the
+public one; safe to re-run; `--dry-run` lists). Until a memo is moved the package reads it from the
+public bucket, so nothing stops playing during the move. The same unsigned GET then answers 403.
+
+Tests: `assets.test.ts` (memos sign, size, read and play in the private bucket and never touch the
+public one; an unmoved memo is still read; no private bucket, no memo methods),
+`migrate-memos.test.ts` (moves only memos, never deletes a public memo whose copy did not arrive,
+dry run, same bucket refused).
+
 ## 0.37.0
 
 **A broadcast is its own page kind.** `template: broadcast` in front matter makes a page one

package/README.md

@@ -673,12 +673,13 @@ recognition, the words appear in the box as the reader speaks. A memo stops at t
 
 Recordings go up through the same `uploads/<name>` route the publisher uses, to
 `<page>/comments/<memo>.<ext>` or, for a signed-in reader's personal note,
-`<page>/personal/<dir>/<memo>.<ext>`. They are never made public: playback is a signed URL
-issued beside the comment or note it belongs to. That needs the four audio methods
-`createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`, `audioUrl`); a host
-with its own `ArtifactAssets` and none of them keeps memos on the reader's device. On a bucket
-with bucket-wide public read, a recording is readable by anyone holding its path (the paths are
-unguessable); keep the bucket per-object public to have the signed-URL guarantee.
+`<page>/personal/<dir>/<memo>.<ext>`, in the PRIVATE bucket (`privateBucket`, the same one
+`media: private` uses). They are never made public: playback is a signed URL, valid about an hour,
+issued beside the comment or note it belongs to, and an unsigned GET is refused (403). That needs the
+four audio methods `createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`,
+`audioUrl`), which it defines only when it is given a private bucket; a host without one, or with
+its own `ArtifactAssets` and none of them, keeps memos on the reader's device. Memos recorded before
+0.38.0 sat in the public bucket: `scripts/migrate-memos-private.mjs` moves them (see CHANGELOG).
 
 To transcribe on the server, pass `transcribe` and add the route. The key stays on the server;
 without `transcribe` the route answers 404 and readers keep the browser's live transcript (or an

package/lib/artifacts/assets.js

@@ -108,12 +108,44 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        async deletePage(id) {
+            // An empty or path-shaped id would make the prefix wider than one page.
+            if (!ARTIFACT_ID_RE.test(id))
+                throw new Error('not an artifact id');
+            let n = 0;
+            for (const b of priv ? [bucket, priv] : [bucket]) {
+                const [files] = await b.getFiles({ prefix: `${clean}/${id}/` });
+                for (const f of files)
+                    await f.delete();
+                n += files.length;
+            }
+            return n;
+        },
+    };
+    if (!priv)
+        return assets;
+    const privateFile = (id, stored) => priv.file(`${clean}/${id}/private/${stored}`);
+    // READERS' VOICE MEMOS LIVE IN THE PRIVATE BUCKET (0.38.0). Until then they went to the public
+    // bucket, unlisted and read through signed URLs, but a bucket-wide public read grant served any
+    // memo to anyone holding its path, unsigned. A memo recorded before 0.38.0 is still read from the
+    // public bucket until scripts/migrate-memos-private.mjs moves it; nothing new is written there.
+    const memo = (id, path) => priv.file(`${clean}/${id}/${path}`);
+    const legacyMemo = (id, path) => bucket.file(`${clean}/${id}/${path}`);
+    const memoFile = async (id, path) => {
+        const f = memo(id, path);
+        if ((await f.exists())[0])
+            return f;
+        const old = legacyMemo(id, path);
+        return (await old.exists())[0] ? old : null;
+    };
+    return {
+        ...assets,
         // The size cap rides in the signature (`x-goog-content-length-range`), so the bucket itself
         // refuses an oversize body; the browser must send the returned headers verbatim.
         async signAudioUpload(id, path, contentType) {
             const range = `0,${MAX_AUDIO_BYTES}`;
             const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600', 'x-goog-content-length-range': range };
-            const [uploadUrl] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({
+            const [uploadUrl] = await memo(id, path).getSignedUrl({
                 version: 'v4',
                 action: 'write',
                 expires: Date.now() + 15 * 60 * 1000,
@@ -123,44 +155,24 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             return { uploadUrl, headers };
         },
         async audioSize(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [meta] = await file.getMetadata();
             return Number(meta.size ?? 0);
         },
         async readAudio(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [bytes] = await file.download();
             return bytes;
         },
         async audioUrl(id, path) {
-            const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            const file = (await memoFile(id, path)) ?? memo(id, path);
+            const [url] = await file.getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
             return url;
         },
-        async deletePage(id) {
-            // An empty or path-shaped id would make the prefix wider than one page.
-            if (!ARTIFACT_ID_RE.test(id))
-                throw new Error('not an artifact id');
-            let n = 0;
-            for (const b of priv ? [bucket, priv] : [bucket]) {
-                const [files] = await b.getFiles({ prefix: `${clean}/${id}/` });
-                for (const f of files)
-                    await f.delete();
-                n += files.length;
-            }
-            return n;
-        },
-    };
-    if (!priv)
-        return assets;
-    const privateFile = (id, stored) => priv.file(`${clean}/${id}/private/${stored}`);
-    return {
-        ...assets,
         async putPrivate(id, name, bytes, contentType) {
             const stored = hashedName(name, bytes);
             await privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });

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';
@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.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';
@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 // Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';

package/lib/artifacts/migrate-memos.d.ts

@@ -0,0 +1,14 @@
+import type { Bucket } from '@google-cloud/storage';
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export declare const MEMO_KEY: RegExp;
+export interface MemoMigration {
+    moved: string[];
+    alreadyPrivate: string[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+export declare function migrateMemosToPrivate(bucket: Bucket, privateBucket: Bucket, prefix: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<MemoMigration>;

package/lib/artifacts/migrate-memos.js

@@ -0,0 +1,36 @@
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export const MEMO_KEY = /^[^/]+\/(?:comments\/[^/]+|personal\/[^/]+\/[^/]+)\.(?:webm|m4a|mp4|ogg|wav)$/;
+export async function migrateMemosToPrivate(bucket, privateBucket, prefix, { dryRun = false } = {}) {
+    if (privateBucket.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const clean = prefix.replace(/^\/+|\/+$/g, '');
+    const [files] = await bucket.getFiles({ prefix: `${clean}/` });
+    const out = { moved: [], alreadyPrivate: [], failed: [] };
+    for (const f of files) {
+        const rel = f.name.slice(clean.length + 1);
+        if (!MEMO_KEY.test(rel))
+            continue;
+        try {
+            const dest = privateBucket.file(f.name);
+            if ((await dest.exists())[0]) {
+                if (!dryRun)
+                    await f.delete();
+                out.alreadyPrivate.push(f.name);
+                continue;
+            }
+            if (dryRun) {
+                out.moved.push(f.name);
+                continue;
+            }
+            await f.copy(dest);
+            if (!(await dest.exists())[0])
+                throw new Error('the copy did not arrive in the private bucket');
+            await f.delete();
+            out.moved.push(f.name);
+        }
+        catch (e) {
+            out.failed.push({ key: f.name, error: e.message });
+        }
+    }
+    return out;
+}

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.37.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",