From a18721dae7da00f51150b6fe5305fadf3d376490 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 7 Oct 2026 03:13:58 +1100
Subject: [PATCH 1/2] perf(demos): paint the Skill page demo from its first
 screen

The Skill page's largest paint was a lazy full-page screenshot, up to 6000 pixels tall. The recorder now keeps a first-screen poster for a taller page. The page loads it eagerly at high priority and fetches the whole page only when the window scrolls.
---
 layers/registry/app/components/_SkillDemo.vue | 43 +++-------
 .../app/components/_SkillDemoShot.vue         | 80 +++++++++++++++++++
 layers/registry/server/utils/skill-demos.ts   | 12 +++
 scripts/record-skill-demo.ts                  | 19 ++++-
 test/unit/skill-demos.test.ts                 | 17 ++++
 5 files changed, 137 insertions(+), 34 deletions(-)
 create mode 100644 layers/registry/app/components/_SkillDemoShot.vue

diff --git a/layers/registry/app/components/_SkillDemo.vue b/layers/registry/app/components/_SkillDemo.vue
index 4edab881..4e642f48 100644
--- a/layers/registry/app/components/_SkillDemo.vue
+++ b/layers/registry/app/components/_SkillDemo.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { SkillDemoView } from '../../server/utils/skill-demos'
 import { demoAgentIcon, demoModelLabel } from '#shared/demo-recording'
+import SkillDemoShot from './_SkillDemoShot.vue'
 
 /**
  * One demo (GLOSSARY "demo"): the prompt, the output an Agent made with this
@@ -15,6 +16,10 @@ const mobileShot = computed(() => demo.shots.find(shot => shot.viewport === 'mob
 const recordedLabel = computed(() => `Recorded with ${demo.agent}, ${demoModelLabel(demo.model)}`)
 
 const live = ref(false)
+
+/** The screens each twin window hides on; the styles below repeat them. */
+const PHONE_WINDOW_MEDIA = '(max-width: 47.99rem)'
+const DESKTOP_WINDOW_MEDIA = '(min-width: 48rem)'
 </script>
 
 <template>
@@ -66,42 +71,26 @@ const live = ref(false)
     <!-- Each shot is the whole page, so it sits in a window the size of one screen and scrolls. -->
     <!-- One shot per device: the phone shot on phones when one exists, the desktop shot elsewhere. -->
     <div v-else class="mt-4">
-      <div
+      <SkillDemoShot
         v-if="desktopShot"
+        :shot="desktopShot"
+        :skip-media="mobileShot ? PHONE_WINDOW_MEDIA : undefined"
         class="skill-demo__window"
         :class="{ 'skill-demo__window--desktop-only': mobileShot }"
         :style="{ aspectRatio: '16 / 10' }"
         :tabindex="desktopShot.height > desktopShot.width * 10 / 16 ? 0 : undefined"
         role="group"
         aria-label="Desktop screenshot. Scroll to see the whole page."
-      >
-        <img
-          :src="desktopShot.src"
-          :width="desktopShot.width"
-          :height="desktopShot.height"
-          :alt="desktopShot.alt"
-          loading="lazy"
-          decoding="async"
-          class="skill-demo__shot"
-        >
-      </div>
-      <div
+      />
+      <SkillDemoShot
         v-if="mobileShot"
+        :shot="mobileShot"
+        :skip-media="DESKTOP_WINDOW_MEDIA"
         class="skill-demo__window skill-demo__window--mobile"
         :tabindex="mobileShot.height > 844 ? 0 : undefined"
         role="group"
         aria-label="Phone screenshot. Scroll to see the whole page."
-      >
-        <img
-          :src="mobileShot.src"
-          :width="mobileShot.width"
-          :height="mobileShot.height"
-          :alt="mobileShot.alt"
-          loading="lazy"
-          decoding="async"
-          class="skill-demo__shot"
-        >
-      </div>
+      />
     </div>
 
     <div class="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2">
@@ -171,12 +160,6 @@ const live = ref(false)
   outline-offset: 2px;
 }
 
-.skill-demo__shot {
-  display: block;
-  width: 100%;
-  height: auto;
-}
-
 /*
  * Full width and a fixed height, not an aspect ratio: a max-height on an
  * aspect-ratio box shrinks its width too, which left a narrow strip.
diff --git a/layers/registry/app/components/_SkillDemoShot.vue b/layers/registry/app/components/_SkillDemoShot.vue
new file mode 100644
index 00000000..14b0e5ce
--- /dev/null
+++ b/layers/registry/app/components/_SkillDemoShot.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import type { SkillDemoShot } from '../../server/utils/skill-demos'
+import { useEventListener } from '@vueuse/core'
+
+/**
+ * One full-page screenshot inside a window one screen tall. The demo sits
+ * above the fold, so the window is the Skill page's largest paint: it loads
+ * the shot's first screen eagerly at high priority, and the whole page only
+ * once someone scrolls the window. The box already has the whole page's
+ * height, so the window scrolls before that image arrives.
+ *
+ * `skipMedia` names the screens where a twin window shows instead. There the
+ * picture resolves to an empty pixel, so a hidden window downloads nothing.
+ */
+const { shot, skipMedia } = defineProps<{
+  shot: SkillDemoShot
+  skipMedia?: string
+}>()
+
+/** A 1x1 transparent GIF: what the hidden twin resolves to. */
+const EMPTY_IMAGE = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
+
+const root = useTemplateRef<HTMLElement>('root')
+const first = computed(() => shot.poster ?? shot)
+const wholePage = ref(false)
+
+useEventListener(root, 'scroll', () => {
+  wholePage.value = true
+}, { passive: true, once: true })
+</script>
+
+<template>
+  <div ref="root">
+    <div class="skill-demo-shot" :style="{ aspectRatio: `${shot.width} / ${shot.height}` }">
+      <picture>
+        <source v-if="skipMedia" :media="skipMedia" :srcset="EMPTY_IMAGE">
+        <img
+          :src="first.src"
+          :width="first.width"
+          :height="first.height"
+          :alt="shot.alt"
+          fetchpriority="high"
+          decoding="async"
+          class="skill-demo-shot__first"
+        >
+      </picture>
+      <img
+        v-if="shot.poster && wholePage"
+        :src="shot.src"
+        :width="shot.width"
+        :height="shot.height"
+        alt=""
+        decoding="async"
+        class="skill-demo-shot__whole"
+      >
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.skill-demo-shot {
+  position: relative;
+  inline-size: 100%;
+}
+
+.skill-demo-shot picture,
+.skill-demo-shot__first {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
+}
+
+/* Over the first screen, which it repeats, so the swap shows no seam. */
+.skill-demo-shot__whole {
+  position: absolute;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+}
+</style>
diff --git a/layers/registry/server/utils/skill-demos.ts b/layers/registry/server/utils/skill-demos.ts
index 6be474b6..fd2316ae 100644
--- a/layers/registry/server/utils/skill-demos.ts
+++ b/layers/registry/server/utils/skill-demos.ts
@@ -27,6 +27,15 @@ const shotSchema = z.object({
   height: z.number().int().positive(),
   alt: z.string().min(1),
   viewport: z.enum(['desktop', 'mobile']),
+  /**
+   * The first screen of a shot taller than one screen, at the shot's width and
+   * the viewport's height. The Skill page paints it first and loads the full
+   * page only when someone scrolls the window.
+   */
+  poster: z.object({
+    file: z.string().regex(/^[\w-]+\.jpg$/),
+    height: z.number().int().positive(),
+  }).optional(),
 })
 
 const videoSchema = z.object({
@@ -102,6 +111,8 @@ export interface SkillDemoShot {
   height: number
   alt: string
   viewport: 'desktop' | 'mobile'
+  /** The first screen, when the shot runs longer than one. */
+  poster: { src: string, width: number, height: number } | null
 }
 
 export interface SkillDemoVideo {
@@ -170,6 +181,7 @@ export function presentSkillDemo(demo: SkillDemoRecord, currentCommit: string |
       height: shot.height,
       alt: shot.alt,
       viewport: shot.viewport,
+      poster: shot.poster ? { src: `${media}/${shot.poster.file}`, width: shot.width, height: shot.poster.height } : null,
     })),
   }
 }
diff --git a/scripts/record-skill-demo.ts b/scripts/record-skill-demo.ts
index affe00b3..91baf5e4 100644
--- a/scripts/record-skill-demo.ts
+++ b/scripts/record-skill-demo.ts
@@ -15,8 +15,9 @@
  *    `npx skilld run`, then gets the prompt word for word. `--seed` copies a
  *    folder in first, and `--setup` says so on the demo.
  * 3. An HTML output gets full-page screenshots at desktop width, and at phone
- *    width when the page fits a phone. An MP4 output is re-encoded small and
- *    gets a poster frame.
+ *    width when the page fits a phone. A page taller than one screen also gets
+ *    a poster: its first screen alone, which the Skill page paints first. An
+ *    MP4 output is re-encoded small and gets a poster frame.
  * 4. Uploads the media to the `skilld-demo-media` R2 bucket with `cf`, under
  *    content-hashed names, copies an HTML page to the registry's
  *    `server/demos/`, and upserts the entry in `server/data/skill-demos.json`.
@@ -112,6 +113,8 @@ interface Shot {
   height: number
   alt: string
   viewport: 'desktop' | 'mobile'
+  /** The first screen, for a shot taller than one. */
+  poster?: { file: string, height: number }
 }
 
 interface Video {
@@ -317,12 +320,17 @@ async function screenshot(page: string, dir: string, prompt: string): Promise<Sh
     const shotHeight = Math.max(height, Math.min(pageHeight, MAX_SHOT_HEIGHT))
     const file = `${viewport}.jpg`
     await tab.screenshot({ path: join(dir, file), type: 'jpeg', quality: 82, fullPage: true, clip: { x: 0, y: 0, width, height: shotHeight } })
+    // The first screen alone, so the Skill page can paint the demo before the whole page downloads.
+    const poster = shotHeight > height ? `${viewport}-poster.jpg` : null
+    if (poster)
+      await tab.screenshot({ path: join(dir, poster), type: 'jpeg', quality: 82, clip: { x: 0, y: 0, width, height } })
     shots.push({
       file,
       width,
       height: shotHeight,
       viewport,
       alt: `${viewport === 'desktop' ? 'Desktop' : 'Phone'} screenshot of the page the Agent built for: ${prompt.slice(0, 120)}`,
+      ...(poster ? { poster: { file: poster, height } } : {}),
     })
     await context.close()
   }
@@ -456,11 +464,14 @@ async function publishMedia(owner: string, repo: string, name: string, dir: stri
 
 /** Stages, uploads, and renames the media of one demo. */
 async function publishDemoMedia(owner: string, repo: string, name: string, dir: string, media: Pick<DemoEntry, 'video' | 'shots'>): Promise<Pick<DemoEntry, 'video' | 'shots'>> {
-  const files = [...new Set([...media.shots.map(shot => shot.file), ...(media.video ? [media.video.file, media.video.poster] : [])])]
+  const files = [...new Set([
+    ...media.shots.flatMap(shot => shot.poster ? [shot.file, shot.poster.file] : [shot.file]),
+    ...(media.video ? [media.video.file, media.video.poster] : []),
+  ])]
   const names = await publishMedia(owner, repo, name, dir, files)
   const to = (file: string) => names.get(file) ?? file
   return {
-    shots: media.shots.map(shot => ({ ...shot, file: to(shot.file) })),
+    shots: media.shots.map(shot => ({ ...shot, file: to(shot.file), ...(shot.poster ? { poster: { ...shot.poster, file: to(shot.poster.file) } } : {}) })),
     ...(media.video ? { video: { ...media.video, file: to(media.video.file), poster: to(media.video.poster) } } : {}),
   }
 }
diff --git a/test/unit/skill-demos.test.ts b/test/unit/skill-demos.test.ts
index 556c90e0..496e93ec 100644
--- a/test/unit/skill-demos.test.ts
+++ b/test/unit/skill-demos.test.ts
@@ -39,6 +39,23 @@ describe('presentSkillDemo', () => {
   })
 })
 
+describe('presentSkillDemo first-screen posters', () => {
+  it('serves a tall shot with its first screen, at the shot width', () => {
+    const view = presentSkillDemo(demo({
+      shots: [{ file: 'desktop.jpg', width: 1440, height: 4102, alt: 'Desktop screenshot', viewport: 'desktop', poster: { file: 'desktop-poster.jpg', height: 900 } }],
+    }), null, 'https://media.example')
+    expect(view.shots[0]?.poster).toEqual({
+      src: 'https://media.example/demos/anthropics/skills/frontend-design/desktop-poster.jpg',
+      width: 1440,
+      height: 900,
+    })
+  })
+
+  it('gives a one-screen shot no poster, since the shot is its own first screen', () => {
+    expect(presentSkillDemo(demo(), null).shots[0]?.poster).toBeNull()
+  })
+})
+
 describe('presentSkillDemo for a video Skill', () => {
   it('serves the video and its poster, and offers no live page without one', () => {
     const view = presentSkillDemo(demo({

From 3fcf2cef939e7ec38d685babfb4bea5d7e3b6f35 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 7 Oct 2026 03:13:59 +1100
Subject: [PATCH 2/2] chore(demos): reshoot tall page demos with posters

Retaken with pnpm demo:record --reshoot from each kept output. Demos one screen tall need no poster and stay as they were.
---
 layers/registry/server/data/skill-demos.json | 74 ++++++++++++++++----
 1 file changed, 59 insertions(+), 15 deletions(-)

diff --git a/layers/registry/server/data/skill-demos.json b/layers/registry/server/data/skill-demos.json
index ba77365b..5c3c5e14 100644
--- a/layers/registry/server/data/skill-demos.json
+++ b/layers/registry/server/data/skill-demos.json
@@ -14,18 +14,26 @@
       "outputFile": "index.html",
       "shots": [
         {
-          "file": "desktop-2a201b3766.jpg",
+          "file": "desktop-d514027082.jpg",
           "width": 1440,
           "height": 4102,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Build a single-file landing page for Tidepool, a tide-chart app for surfers. Inline all CSS and JavaScript. Save it as i"
+          "alt": "Desktop screenshot of the page the Agent built for: Build a single-file landing page for Tidepool, a tide-chart app for surfers. Inline all CSS and JavaScript. Save it as i",
+          "poster": {
+            "file": "desktop-poster-3180cdf6a9.jpg",
+            "height": 900
+          }
         },
         {
-          "file": "mobile-da8e537494.jpg",
+          "file": "mobile-32b72a3ea8.jpg",
           "width": 390,
           "height": 5065,
           "viewport": "mobile",
-          "alt": "Phone screenshot of the page the Agent built for: Build a single-file landing page for Tidepool, a tide-chart app for surfers. Inline all CSS and JavaScript. Save it as i"
+          "alt": "Phone screenshot of the page the Agent built for: Build a single-file landing page for Tidepool, a tide-chart app for surfers. Inline all CSS and JavaScript. Save it as i",
+          "poster": {
+            "file": "mobile-poster-f9b907cc90.jpg",
+            "height": 844
+          }
         }
       ],
       "authorName": "Anthropic",
@@ -49,7 +57,11 @@
           "width": 1440,
           "height": 927,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Keep the default style guide. Draw an architecture diagram for Tidewhisk, a fictional ferry-booking service: web app, AP"
+          "alt": "Desktop screenshot of the page the Agent built for: Keep the default style guide. Draw an architecture diagram for Tidewhisk, a fictional ferry-booking service: web app, AP",
+          "poster": {
+            "file": "desktop-poster-caff9f689a.jpg",
+            "height": 900
+          }
         }
       ],
       "authorName": "Cathryn Lavery",
@@ -75,14 +87,22 @@
           "width": 1440,
           "height": 6000,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Build a landing page for Glossmere, a fictional invoicing app for freelance translators that bills per word and per lang"
+          "alt": "Desktop screenshot of the page the Agent built for: Build a landing page for Glossmere, a fictional invoicing app for freelance translators that bills per word and per lang",
+          "poster": {
+            "file": "desktop-poster-2aeacf6003.jpg",
+            "height": 900
+          }
         },
         {
           "file": "mobile-4d54ba1970.jpg",
           "width": 390,
           "height": 6000,
           "viewport": "mobile",
-          "alt": "Phone screenshot of the page the Agent built for: Build a landing page for Glossmere, a fictional invoicing app for freelance translators that bills per word and per lang"
+          "alt": "Phone screenshot of the page the Agent built for: Build a landing page for Glossmere, a fictional invoicing app for freelance translators that bills per word and per lang",
+          "poster": {
+            "file": "mobile-poster-6ab5a5de6f.jpg",
+            "height": 844
+          }
         }
       ]
     },
@@ -224,11 +244,15 @@
       "outputFile": "flow.html",
       "shots": [
         {
-          "file": "desktop-70a1bca51d.jpg",
+          "file": "desktop-5bb32b6afc.jpg",
           "width": 1440,
           "height": 1060,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Show me how Cogwhistle, a fictional bike-courier dispatch app, assigns a new delivery to a rider, from order to pickup. "
+          "alt": "Desktop screenshot of the page the Agent built for: Show me how Cogwhistle, a fictional bike-courier dispatch app, assigns a new delivery to a rider, from order to pickup. ",
+          "poster": {
+            "file": "desktop-poster-2dbf5169f1.jpg",
+            "height": 900
+          }
         }
       ],
       "authorName": "HumanLayer",
@@ -252,14 +276,22 @@
           "width": 1440,
           "height": 1164,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Build pricing.html, a single-file HTML pricing section for Glintwork, a fictional photo-editing app: three plan cards, a"
+          "alt": "Desktop screenshot of the page the Agent built for: Build pricing.html, a single-file HTML pricing section for Glintwork, a fictional photo-editing app: three plan cards, a",
+          "poster": {
+            "file": "desktop-poster-21e78314b8.jpg",
+            "height": 900
+          }
         },
         {
           "file": "mobile-7180f99b12.jpg",
           "width": 390,
           "height": 2192,
           "viewport": "mobile",
-          "alt": "Phone screenshot of the page the Agent built for: Build pricing.html, a single-file HTML pricing section for Glintwork, a fictional photo-editing app: three plan cards, a"
+          "alt": "Phone screenshot of the page the Agent built for: Build pricing.html, a single-file HTML pricing section for Glintwork, a fictional photo-editing app: three plan cards, a",
+          "poster": {
+            "file": "mobile-poster-8abcea89bd.jpg",
+            "height": 844
+          }
         }
       ],
       "authorName": "Jakub Krehel",
@@ -348,14 +380,22 @@
           "width": 1440,
           "height": 905,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Build a one-page dashboard for Wrenfold Bikes, a town bike share. This week's rides by station: Harbour 412, Station Roa"
+          "alt": "Desktop screenshot of the page the Agent built for: Build a one-page dashboard for Wrenfold Bikes, a town bike share. This week's rides by station: Harbour 412, Station Roa",
+          "poster": {
+            "file": "desktop-poster-8fa468cdbd.jpg",
+            "height": 900
+          }
         },
         {
           "file": "mobile-2c917bf37f.jpg",
           "width": 390,
           "height": 1751,
           "viewport": "mobile",
-          "alt": "Phone screenshot of the page the Agent built for: Build a one-page dashboard for Wrenfold Bikes, a town bike share. This week's rides by station: Harbour 412, Station Roa"
+          "alt": "Phone screenshot of the page the Agent built for: Build a one-page dashboard for Wrenfold Bikes, a town bike share. This week's rides by station: Harbour 412, Station Roa",
+          "poster": {
+            "file": "mobile-poster-4e7f952eb1.jpg",
+            "height": 844
+          }
         }
       ]
     },
@@ -375,11 +415,15 @@
       "outputFile": "index.html",
       "shots": [
         {
-          "file": "desktop-5912c3c3eb.jpg",
+          "file": "desktop-2bcdf1a732.jpg",
           "width": 1440,
           "height": 6000,
           "viewport": "desktop",
-          "alt": "Desktop screenshot of the page the Agent built for: Build a landing page for Kilnmarrow, a fictional shared pottery studio that rents kiln shelf space by the firing. Don't "
+          "alt": "Desktop screenshot of the page the Agent built for: Build a landing page for Kilnmarrow, a fictional shared pottery studio that rents kiln shelf space by the firing. Don't ",
+          "poster": {
+            "file": "desktop-poster-77ef6d0637.jpg",
+            "height": 900
+          }
         }
       ]
     },