@@ -119,6 +119,9 @@ FONT=$(shotstack ingest upload ./Brand.woff2 --watch --output json | tail -n1 |
 - **Same account and environment only.** A file ingested on `stage` works in `stage` renders, not in `v1`, and another account's files are refused. Every other remote URL is still blocked.
 - **10 MiB per file, 25 MiB per page.** A file counts once for every place the page references it, so reference a large image once (a CSS class, say) and reuse the class.
 - **Size images to the clip.** A photo much larger than the clip makes a heavier page and a slower capture. If the source has a WebP rendition named `html5-512`, `html5-1024`, `html5-2048` or `html5-4096`, the renderer uses the smallest one that covers the clip's longest edge; otherwise it uses the original.
+<!-- surface:cli -->
+- `shotstack ingest upload --watch` and `ingest fetch --watch` request those renditions for an image and wait up to 60 s for them, so the `source` URL is all the page needs.
+<!-- /surface -->
 - **A file that can't be used fails the render**, for example one that's missing, too large, or not an image or font.
 - **Studio's preview doesn't load ingested files yet**, so they show as missing there. The render is unaffected.
 <!-- surface:cli -->
 
@@ -85,6 +85,11 @@ An `html5` page can use images and fonts you ingested by putting their
 The file must belong to the same account and environment as the render. Limits
 and details are in [`html5.md`](html5.md).
 
+With `--watch`, an image upload or fetch also requests smaller WebP copies
+(`html5-512` up to `html5-4096`, only those smaller than the image) and waits
+up to 60 s for them. They're listed under `outputs.renditions`; the renderer
+picks one for the clip size, so keep using the `source` URL.
+
 ## Fetch a remote URL instead of uploading
 
 If the media is already at a URL but you want Shotstack to host its own copy
 
@@ -9,9 +9,22 @@ import { withRecording, commandArgv } from "../recorder.ts";
 
 const POLL_INTERVAL_MS = 3000;
 const SOURCE_TERMINAL_STATES = new Set(["ready", "failed", "deleted", "overwritten"]);
+const RENDITION_TERMINAL_STATES = new Set(["ready", "failed", "deleted", "overwritten"]);
+
+// The html5 renderer uses the smallest of these that covers the clip, or the source when it's missing.
+const HTML5_STEPS = [512, 1024, 2048, 4096];
+const STEP_WAIT_MS = 60_000;
+// No GIF or SVG: a WebP copy keeps only a GIF's first frame and loses an SVG's vectors.
+const STEP_IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".tif", ".tiff"]);
 
 export type SourceStatus = "queued" | "importing" | "ready" | "failed" | "deleted" | "overwritten";
 
+export interface RenditionAttributes {
+  status: string;
+  url?: string;
+  transformation?: { size?: { width?: number; height?: number } };
+}
+
 export interface SourceAttributes {
   id: string;
   status: SourceStatus;
@@ -21,6 +34,7 @@ export interface SourceAttributes {
   height?: number;
   duration?: number;
   error?: string;
+  outputs?: { renditions?: RenditionAttributes[] };
 }
 
 interface UploadResponse {
@@ -148,10 +162,51 @@ async function finishSource(client: Client, id: string, format: OutputFormat, wa
     emit(format, { id }, id);
     return { renderId: id, response: { id } };
   }
-  const final = await pollSource(client, id, format, true);
+  const final = await requestSteps(client, await pollSource(client, id, format, true), format);
   return { renderId: id, response: sourceView(final), exitCode: final.status === "failed" ? 1 : 0 };
 }
 
+export function html5Steps(source: SourceAttributes) {
+  const { status, width, height } = source;
+  if (status !== "ready" || !width || !height || !source.source) return [];
+  if (!STEP_IMAGE_EXTENSIONS.has(extname(new URL(source.source).pathname).toLowerCase())) return [];
+  // One dimension and no fit keeps the aspect ratio.
+  const edge = width >= height ? "width" : "height";
+  return HTML5_STEPS.filter((step) => step < Math.max(width, height)).map((step) => ({
+    format: "webp",
+    size: { [edge]: step },
+    filename: `html5-${step}`,
+  }));
+}
+
+export async function requestSteps(
+  client: Client,
+  source: SourceAttributes,
+  format: OutputFormat,
+  { timeoutMs = STEP_WAIT_MS, intervalMs = POLL_INTERVAL_MS } = {},
+): Promise<SourceAttributes> {
+  const steps = html5Steps(source);
+  if (!steps.length) return source;
+  const path = `/sources/${encodeURIComponent(source.id)}`;
+  try {
+    await client.post(`${path}/renditions`, { outputs: { renditions: steps } });
+  } catch (err) {
+    // The source renders without its steps, so the upload still succeeds.
+    console.error(`Could not request html5 size steps: ${err instanceof Error ? err.message : String(err)}`);
+    return source;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const attributes = (await client.get<SourceResponse>(path)).data.attributes;
+    emit(format, sourceView(attributes), formatHuman(attributes));
+    const renditions = attributes.outputs?.renditions ?? [];
+    const pending =
+      renditions.length < steps.length || renditions.some((r) => !RENDITION_TERMINAL_STATES.has(r.status));
+    if (!pending || Date.now() >= deadline) return attributes;
+    await sleep(intervalMs);
+  }
+}
+
 export async function pollSource(
   client: Client,
   id: string,
@@ -231,14 +286,23 @@ function sourceView(a: SourceAttributes): SourceAttributes {
   if (a.height) view.height = a.height;
   if (a.duration) view.duration = a.duration;
   if (a.error) view.error = a.error;
+  const renditions = a.outputs?.renditions;
+  if (renditions?.length) view.outputs = { renditions: renditions.map(({ status, url }) => ({ status, url })) };
   return view;
 }
 
 function formatHuman(a: SourceAttributes): string {
   const parts: string[] = [a.status];
   if (a.source) parts.push(a.source);
   if (a.error) parts.push(`error: ${a.error}`);
-  return parts.join("  ");
+  return parts.join("  ") + (a.outputs?.renditions ?? []).map(renditionLine).join("");
+}
+
+// Ingest gives a rendition its URL only once it's ready, so until then it goes by its size.
+function renditionLine(r: RenditionAttributes): string {
+  const size = r.transformation?.size;
+  const label = r.url ?? (size ? `${size.width ?? size.height}px` : "");
+  return `\n  ${r.status}  ${label}`.trimEnd();
 }
 
 function sleep(ms: number): Promise<void> {
 
@@ -1,5 +1,12 @@
-import { describe, test, expect, afterEach, mock } from "bun:test";
-import { guessContentType, putToSignedUrl, pollSource, type SourceAttributes } from "../src/commands/ingest.ts";
+import { describe, test, expect, afterEach, mock, spyOn } from "bun:test";
+import {
+  guessContentType,
+  putToSignedUrl,
+  pollSource,
+  html5Steps,
+  requestSteps,
+  type SourceAttributes,
+} from "../src/commands/ingest.ts";
 import type { Client } from "../src/http/client.ts";
 import { ApiError } from "../src/http/client.ts";
 
@@ -102,3 +109,106 @@ describe("pollSource", () => {
     expect(result.status).toBe("failed");
   });
 });
+
+const SRC = "https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/owner/src-1/source";
+
+function readySource(ext: string, width?: number, height?: number): SourceAttributes {
+  const source: SourceAttributes = { id: "src-1", status: "ready", source: `${SRC}.${ext}` };
+  if (width) source.width = width;
+  if (height) source.height = height;
+  return source;
+}
+
+describe("html5Steps", () => {
+  test("sizes a landscape image's steps by width, below its long edge", () => {
+    expect(html5Steps(readySource("jpg", 3000, 2000))).toEqual([
+      { format: "webp", size: { width: 512 }, filename: "html5-512" },
+      { format: "webp", size: { width: 1024 }, filename: "html5-1024" },
+      { format: "webp", size: { width: 2048 }, filename: "html5-2048" },
+    ]);
+  });
+
+  test("sizes a portrait image's steps by height", () => {
+    expect(html5Steps(readySource("PNG", 1200, 1600))).toEqual([
+      { format: "webp", size: { height: 512 }, filename: "html5-512" },
+      { format: "webp", size: { height: 1024 }, filename: "html5-1024" },
+    ]);
+  });
+
+  test("never requests a step as large as the source", () => {
+    expect(html5Steps(readySource("webp", 1024, 768)).map((s) => s.filename)).toEqual(["html5-512"]);
+    expect(html5Steps(readySource("jpeg", 400, 300))).toEqual([]);
+  });
+
+  test("skips sources that aren't raster images, aren't ready or have no size", () => {
+    for (const ext of ["mp4", "gif", "svg", "woff2"]) expect(html5Steps(readySource(ext, 3000, 2000))).toEqual([]);
+    expect(html5Steps({ ...readySource("jpg", 3000, 2000), status: "importing" })).toEqual([]);
+    expect(html5Steps(readySource("jpg"))).toEqual([]);
+  });
+});
+
+describe("requestSteps", () => {
+  type Step = { status: string; url: string };
+  function stepsClient(rounds: Step[][], postError?: Error) {
+    let i = 0;
+    const post = mock(async () => {
+      if (postError) throw postError;
+      return {};
+    });
+    const get = mock(async () => {
+      const renditions = rounds[Math.min(i, rounds.length - 1)]!;
+      i += 1;
+      return { data: { type: "source", id: "src-1", attributes: { ...readySource("jpg", 1600, 900), outputs: { renditions } } } };
+    });
+    return { client: { post, get } as unknown as Client, post, get };
+  }
+  const step = (status: string, s: number) => ({ status, url: `https://renditions.example.com/owner/src-1/html5-${s}.webp` });
+
+  test("requests the steps once, then waits until each one is done", async () => {
+    const { client, post, get } = stepsClient([
+      [step("processing", 512), step("queued", 1024)],
+      [step("ready", 512), step("failed", 1024)],
+    ]);
+    const result = await requestSteps(client, readySource("jpg", 1600, 900), "json", { timeoutMs: 60_000, intervalMs: 0 });
+
+    expect(post.mock.calls).toEqual([
+      ["/sources/src-1/renditions", { outputs: { renditions: html5Steps(readySource("jpg", 1600, 900)) } }],
+    ]);
+    expect(get.mock.calls.length).toBe(2);
+    expect(result.outputs?.renditions?.map((r) => r.status)).toEqual(["ready", "failed"]);
+  });
+
+  test("returns the steps still processing when the wait runs out", async () => {
+    const { client } = stepsClient([[step("processing", 512), step("processing", 1024)]]);
+    const result = await requestSteps(client, readySource("jpg", 1600, 900), "json", { timeoutMs: 0, intervalMs: 0 });
+    expect(result.status).toBe("ready");
+    expect(result.outputs?.renditions?.map((r) => r.status)).toEqual(["processing", "processing"]);
+  });
+
+  test("names a step by its size in text output until it has a URL", async () => {
+    const pending = { status: "processing", transformation: { format: "webp", size: { width: 1024 } } };
+    const { client } = stepsClient([[step("ready", 512), pending as unknown as Step]]);
+    const lines: string[] = [];
+    const log = spyOn(console, "log").mockImplementation((line: string) => void lines.push(line));
+    try {
+      await requestSteps(client, readySource("jpg", 1600, 900), "text", { timeoutMs: 0, intervalMs: 0 });
+    } finally {
+      log.mockRestore();
+    }
+    expect(lines.at(-1)).toEndWith("\n  ready  https://renditions.example.com/owner/src-1/html5-512.webp\n  processing  1024px");
+  });
+
+  test("leaves a source with no steps alone", async () => {
+    const { client, post, get } = stepsClient([[]]);
+    const source = readySource("mp4", 1920, 1080);
+    expect(await requestSteps(client, source, "json", { timeoutMs: 0, intervalMs: 0 })).toBe(source);
+    expect(post.mock.calls.length + get.mock.calls.length).toBe(0);
+  });
+
+  test("returns the source when the steps can't be requested", async () => {
+    const { client, get } = stepsClient([[]], new ApiError(400, undefined, "POST /sources/src-1/renditions → 400"));
+    const source = readySource("jpg", 1600, 900);
+    expect(await requestSteps(client, source, "json", { timeoutMs: 60_000, intervalMs: 0 })).toBe(source);
+    expect(get.mock.calls.length).toBe(0);
+  });
+});