feat(sdk): hide best-practice defaults — immutable=true, defer, lazy/async-decode

MajorTal · claude · MajorTal · commit e66b3cdd628c · 2026-04-27T21:56:08.000+02:00
Push the agent-DX defaults all the way: with these on, the agent's typical flow is one line and gets every modern best practice for free.

Defaults flipped:

1. BlobPutOptions.immutable defaults to true. The cdnUrl + sri + tag emitters all require an immutable upload, so the v1.45 default reaches for the best path. Cost: one client-side SHA-256 pass, dominated by network for typical asset sizes (&lt; 1 MB). Storage cost: +128 bytes (one blob_url_refs row). Pass { immutable: false } to opt out for very large uploads where you specifically don't need a content-hashed URL.

2. scriptTag() defaults defer: true. Modern best practice — non-render-blocking when placed in &lt;head&gt;, no-op at end of &lt;body&gt;. async: true overrides defer (the two are mutually exclusive per HTML spec). Pass { defer: false } for the rare sync-required case.

3. imgTag() defaults loading="lazy" + decoding="async". Lazy is harmless for above-fold images (browsers handle the heuristic) and a flat win for the much more common below-fold case. Async decoding moves the decode off the main thread. Both are baseline-supported in all major browsers.

linkTag intentionally NOT changed — crossorigin always emitted because we always emit integrity (SRI requires CORS mode), AND for rel="preload" matching crossorigin is what lets the browser dedupe with the eventual fetch instead of double-fetching.

Tests:

- New: 'defaults to immutable: true' covers the v1.45 default path + cdnUrl/sri/scriptTag work without the agent passing { immutable: true }

- Updated: scriptTag/linkTag/imgTag emitter test asserts the new default attributes (defer, loading=lazy, decoding=async) and the explicit-opt-out paths (defer: false, async: true overriding defer)

- Updated: existing tests that checked sha256=undefined / immutable=false explicitly pass { immutable: false } to preserve their intent

- All 26 SDK tests green

Docs:

- SKILL.md and cli/llms-cli.txt updated to reflect immutable=true as the default and remove the 'always pass { immutable: true }' guidance (no longer needed)

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/SKILL.md b/SKILL.md
@@ -106,21 +106,21 @@ Upload a blob (any size, up to 5 TiB) to project storage via direct-to-S3 presig
 - `content` (optional) — Inline content, ≤ 1 MB. Use only for small text blobs.
 - `content_type` (optional) — MIME type
 - `visibility` (optional, default: `"public"`) — `"public"` (bypasses auth) or `"private"` (requires apikey)
-- `immutable` (optional, default: `false`) — If true with `sha256`, also produces a content-addressed URL that gets `Cache-Control: immutable`.
-- `sha256` (optional) — Required when `immutable: true`. Client-asserted hash; gateway verifies if S3 returns one.
+- `immutable` (optional, **default `true` since v1.45**) — Produces a content-addressed URL that pairs with SRI and never needs cache invalidation. Pass `{ immutable: false }` only when you specifically want to skip the SHA-256 pass on a very large upload (storage cost is identical; immutable just adds the content-hashed URL).
+- `sha256` (optional) — Computed automatically by the SDK when `immutable: true` (the default). You don't need to set this.
 
-**Returns:** an `AssetRef`. The agent-DX way to use it: **upload with `immutable: true`, then call `result.scriptTag()`, `result.linkTag()`, or `result.imgTag()` and paste the output directly into your generated HTML.** The tag emitters return ready-to-use HTML with `src` / `href` set to a content-hashed URL on `pr-<public_id>.run402.com`, `integrity` set to the SRI hash, and `crossorigin` set so browsers verify the bytes.
+**Returns:** an `AssetRef`. The agent-DX way to use it: **call `result.scriptTag()`, `result.linkTag()`, or `result.imgTag()` and paste the output directly into your generated HTML.** The tag emitters return ready-to-use HTML with `src` / `href` set to a content-hashed URL on `pr-<public_id>.run402.com`, `integrity` set to the SRI hash, and `crossorigin` set so browsers verify the bytes. They also bake in modern best-practice attributes — `defer` on `<script>`, `loading="lazy"` + `decoding="async"` on `<img>` — so you don't have to remember.
 
 ```ts
-const logo = await client.blobs.put(projectId, "logo.png", { bytes }, { immutable: true });
+const logo = await client.blobs.put(projectId, "logo.png", { bytes });
 html += logo.imgTag("Company logo");
-// → <img src="https://pr-abc.run402.com/_blob/logo-3a7fc02e.png" alt="Company logo">
+// → <img src="https://pr-abc.run402.com/_blob/logo-3a7fc02e.png" alt="Company logo" loading="lazy" decoding="async">
 
-const app = await client.blobs.put(projectId, "app.js", { content }, { immutable: true });
+const app = await client.blobs.put(projectId, "app.js", { content });
 html += app.scriptTag({ type: "module" });
-// → <script src="https://pr-abc.run402.com/_blob/app-deadbeef.js" type="module" integrity="sha256-…" crossorigin></script>
+// → <script src="https://pr-abc.run402.com/_blob/app-deadbeef.js" type="module" defer integrity="sha256-…" crossorigin></script>
 
-const styles = await client.blobs.put(projectId, "styles.css", { content }, { immutable: true });
+const styles = await client.blobs.put(projectId, "styles.css", { content });
 html += styles.linkTag();
 // → <link rel="stylesheet" href="https://pr-abc.run402.com/_blob/styles-aabbccdd.css" integrity="sha256-…" crossorigin>
 ```
diff --git a/cli/llms-cli.txt b/cli/llms-cli.txt
@@ -411,13 +411,13 @@ run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha ba78... --ti
 `put` response (an `AssetRef`) — the agent-DX way:
 
 ```js
-const asset = await client.blobs.put(projectId, key, { bytes }, { immutable: true });
-html += asset.scriptTag();          // <script src=... integrity=... crossorigin></script>
-html += asset.linkTag();            // <link rel="stylesheet" href=... integrity=... crossorigin>
-html += asset.imgTag("Company logo"); // <img src=... alt="Company logo">
+const asset = await client.blobs.put(projectId, key, { bytes });  // v1.45 defaults to immutable: true
+html += asset.scriptTag();             // <script src=... defer integrity=... crossorigin></script>
+html += asset.linkTag();               // <link rel="stylesheet" href=... integrity=... crossorigin>
+html += asset.imgTag("Company logo");  // <img src=... alt="Company logo" loading="lazy" decoding="async">
 ```
 
-Always upload with `immutable: true` when you plan to embed in HTML/CSS/JS. The tag emitters require it (they bind to a SHA), and the resulting URL is content-addressed → never needs cache invalidation, never breaks on re-deploys, never needs `cdn wait-fresh` follow-up.
+`immutable: true` is the default since v1.45 — the SDK computes the SHA-256 client-side and the gateway returns a content-addressed URL paired with SRI. The resulting URL never needs cache invalidation, never breaks on re-deploys, never needs `cdn wait-fresh` follow-up. Pass `{ immutable: false }` explicitly only when you want to skip the SHA pass on a very large upload (in that case the tag emitters throw because there's no SHA to bind for SRI). The tag emitters also bake in modern best-practice attributes — `defer` on `<script>`, `loading="lazy"` + `decoding="async"` on `<img>` — so the agent doesn't have to remember.
 
 Other AssetRef fields for advanced use:
 - `cdnUrl` — the content-addressed URL the emitters use directly. `https://pr-<public_id>.run402.com/_blob/<key-without-ext>-<8hex>.<ext>`. Served via the v1.33 CDN; guaranteed-reachable.
diff --git a/sdk/src/namespaces/blobs.test.ts b/sdk/src/namespaces/blobs.test.ts
@@ -91,7 +91,15 @@ describe("blobs.put", () => {
     });
 
     const sdk = makeSdk(fetch);
-    const result = await sdk.blobs.put("prj_known", "hello.txt", { content: "hello world\n" });
+    // Pass `immutable: false` explicitly: this test verifies the basic flow
+    // shape (init → PUT → complete) and the legacy non-immutable behavior
+    // (no SHA pre-computation, immutable: false propagated to the gateway).
+    // The v1.45 default is `immutable: true`; the dedicated default-and-
+    // tag-emitter tests below cover that path.
+    const result = await sdk.blobs.put(
+      "prj_known", "hello.txt", { content: "hello world\n" },
+      { immutable: false },
+    );
 
     assert.equal(calls.length, 3);
     assert.equal(calls[0]!.url, "https://api.example.test/storage/v1/uploads");
@@ -112,6 +120,52 @@ describe("blobs.put", () => {
     assert.equal(result.url, "https://cdn.test/hello.txt");
   });
 
+  it("defaults to immutable: true (v1.45) — computes SHA + sends content-hashed flag", async () => {
+    let initBody: Record<string, unknown> | null = null;
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        initBody = JSON.parse(call.body as string);
+        return json({
+          upload_id: "u_d",
+          mode: "single",
+          part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_d/p1", byte_start: 0, byte_end: 2 }],
+        });
+      }
+      if (call.url.startsWith("https://s3.test/")) {
+        return new Response("", { status: 200, headers: { etag: '"e"' } });
+      }
+      if (call.url.endsWith("/complete")) {
+        return json({
+          key: "hello.txt",
+          size_bytes: 3,
+          sha256: "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+          visibility: "public",
+          content_type: "text/plain",
+          immutable_suffix: "ba7816bf",
+          url: "https://cdn.test/hello.txt",
+          immutable_url: "https://cdn.test/hello-ba7816bf.txt",
+          cdn_url: "https://pr-abc.run402.com/_blob/hello.txt",
+          cdn_immutable_url: "https://pr-abc.run402.com/_blob/hello-ba7816bf.txt",
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    // No opts — relying on v1.45 defaults.
+    const asset = await sdk.blobs.put("prj_known", "hello.txt", { content: "abc" });
+    assert.equal(initBody!.immutable, true);
+    assert.equal(
+      initBody!.sha256,
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+    );
+    assert.ok(asset.cdnUrl, "cdnUrl populated by default");
+    assert.ok(asset.sri, "sri populated by default");
+    // Tag emitters work without the agent ever passing { immutable: true }.
+    const tag = asset.scriptTag();
+    assert.match(tag, /integrity="sha256-/);
+  });
+
   it("attaches parts with etags in multipart mode", async () => {
     const { fetch, calls } = mockFetch((call) => {
       if (call.url.endsWith("/storage/v1/uploads") && call.method === "POST") {
@@ -137,7 +191,12 @@ describe("blobs.put", () => {
       throw new Error("unexpected");
     });
     const sdk = makeSdk(fetch);
-    await sdk.blobs.put("prj_known", "multi.bin", { bytes: new Uint8Array(12) });
+    // Pin immutable: false — this test asserts on the multipart-complete
+    // shape, not on the sha-computation path.
+    await sdk.blobs.put(
+      "prj_known", "multi.bin", { bytes: new Uint8Array(12) },
+      { immutable: false },
+    );
     const completeBody = JSON.parse(calls[3]!.body as string);
     assert.deepEqual(completeBody.parts, [
       { part_number: 1, etag: '"e1"' },
@@ -393,36 +452,53 @@ describe("blobs.put — AssetRef widening (v1.45)", () => {
     const sdk = makeSdk(fetch);
     const asset = await sdk.blobs.put("prj_known", "app.js", { content: "abc" }, { immutable: true });
 
-    // Default scriptTag.
+    // Default scriptTag — emits `defer` by default (modern best practice).
     const tag = asset.scriptTag();
     assert.match(tag, /^<script /);
     assert.match(tag, /src="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
+    assert.match(tag, /\bdefer\b/);
     assert.match(tag, /integrity="sha256-[A-Za-z0-9+/]+={0,2}"/);
     assert.match(tag, /crossorigin/);
+    // No async by default.
+    assert.equal(/\basync\b/.test(tag), false);
+
+    // Explicit defer: false opts out.
+    const noDefer = asset.scriptTag({ defer: false });
+    assert.equal(/\bdefer\b/.test(noDefer), false);
 
-    // Module + defer.
+    // Module + explicit defer.
     const moduleTag = asset.scriptTag({ type: "module", defer: true });
     assert.match(moduleTag, /type="module"/);
-    assert.match(moduleTag, / defer /);
+    assert.match(moduleTag, /\bdefer\b/);
+
+    // async: true overrides defer (mutually exclusive per HTML spec).
+    const asyncTag = asset.scriptTag({ async: true });
+    assert.match(asyncTag, /\basync\b/);
+    assert.equal(/\bdefer\b/.test(asyncTag), false);
 
     // Default linkTag (stylesheet).
     const link = asset.linkTag();
     assert.match(link, /^<link /);
     assert.match(link, /rel="stylesheet"/);
     assert.match(link, /href="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
     assert.match(link, /integrity="sha256-/);
+    assert.match(link, /crossorigin/);
 
-    // Custom rel + as (preload).
+    // Custom rel + as (preload). crossorigin still emitted (required for
+    // SRI to be enforced AND for preload-fetch deduping).
     const preload = asset.linkTag({ rel: "preload", as: "font" });
     assert.match(preload, /rel="preload"/);
     assert.match(preload, /as="font"/);
+    assert.match(preload, /crossorigin/);
 
-    // imgTag with alt.
+    // imgTag — emits loading="lazy" + decoding="async" by default.
     const img = asset.imgTag("Company logo");
     assert.match(img, /^<img /);
     assert.match(img, /src="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
     assert.match(img, /alt="Company logo"/);
-    // No SRI on <img>.
+    assert.match(img, /loading="lazy"/);
+    assert.match(img, /decoding="async"/);
+    // No SRI on <img> per HTML spec.
     assert.equal(/integrity=/.test(img), false);
   });
 
diff --git a/sdk/src/namespaces/blobs.ts b/sdk/src/namespaces/blobs.ts
@@ -201,17 +201,30 @@ function buildAssetRef(
     cdn,
 
     scriptTag(opts) {
+      // Default `defer: true` — modern best practice. Defer prevents
+      // render-blocking when placed in <head> and is a no-op when placed
+      // at the end of <body> (the script runs after DOMContentLoaded
+      // either way). Pass `{ defer: false }` to opt out for the rare
+      // case requiring synchronous execution. `async` and `defer` are
+      // mutually exclusive; passing async overrides defer.
       const { url, sri } = requireImmutable("scriptTag");
       const attrs: string[] = [`src="${escapeHtmlAttr(url)}"`];
       if (opts?.type === "module") attrs.push(`type="module"`);
-      if (opts?.defer) attrs.push("defer");
-      if (opts?.async) attrs.push("async");
+      const wantsAsync = opts?.async === true;
+      const wantsDefer = opts?.defer ?? !wantsAsync;
+      if (wantsAsync) attrs.push("async");
+      else if (wantsDefer) attrs.push("defer");
       attrs.push(`integrity="${escapeHtmlAttr(sri)}"`);
       attrs.push("crossorigin");
       return `<script ${attrs.join(" ")}></script>`;
     },
 
     linkTag(opts) {
+      // Always emit crossorigin — required for SRI to actually be
+      // enforced. Without crossorigin the browser silently ignores the
+      // integrity attribute (HTML spec). This applies to rel="preload"
+      // too: matching crossorigin on the preload + the eventual fetch is
+      // what lets the browser dedupe instead of double-fetching.
       const { url, sri } = requireImmutable("linkTag");
       const rel = opts?.rel ?? "stylesheet";
       const attrs: string[] = [`rel="${escapeHtmlAttr(rel)}"`];
@@ -223,12 +236,18 @@ function buildAssetRef(
     },
 
     imgTag(alt) {
-      // <img> doesn't take SRI per HTML5 spec — agents who need integrity
-      // for images should fetch + verify Content-Digest server-side. We
-      // still require immutable so the URL is stable across re-deploys.
+      // Defaults: loading="lazy" + decoding="async" — modern best
+      // practice. Lazy is harmless for above-fold images (browsers
+      // handle the heuristic) and a flat win for the much more common
+      // below-fold case. Async decoding moves the decode off the main
+      // thread. Both are baseline-supported in all major browsers.
+      // <img> doesn't accept SRI per HTML5; the URL is content-hashed
+      // so it's still stable across re-deploys. Agents who need
+      // byte-level integrity for images should verify Content-Digest
+      // server-side.
       const { url } = requireImmutable("imgTag");
       const a = alt ?? "";
-      return `<img src="${escapeHtmlAttr(url)}" alt="${escapeHtmlAttr(a)}">`;
+      return `<img src="${escapeHtmlAttr(url)}" alt="${escapeHtmlAttr(a)}" loading="lazy" decoding="async">`;
     },
   };
 }
@@ -270,7 +289,13 @@ export class Blobs {
     }
 
     const contentType = opts.contentType ?? guessContentType(key);
-    const sha256 = opts.immutable ? await sha256Hex(bytes) : undefined;
+    // v1.45 default: `immutable: true`. The agent-DX surface (cdnUrl, sri,
+    // scriptTag/linkTag/imgTag) only works for content-addressed uploads,
+    // so the default reaches for the best path. Pass `{ immutable: false }`
+    // explicitly when you specifically want a non-content-hashed URL
+    // (e.g. very large file where you want to skip the SHA pass).
+    const immutable = opts.immutable ?? true;
+    const sha256 = immutable ? await sha256Hex(bytes) : undefined;
 
     // 1. Init upload — gateway returns presigned S3 URLs for each part.
     const init = await this.client.request<UploadInitResponse>("/storage/v1/uploads", {
@@ -284,7 +309,7 @@ export class Blobs {
         size_bytes: sizeBytes,
         content_type: contentType,
         visibility: opts.visibility ?? "public",
-        immutable: opts.immutable ?? false,
+        immutable,
         sha256,
       },
       context: "initializing upload",
diff --git a/sdk/src/namespaces/blobs.types.ts b/sdk/src/namespaces/blobs.types.ts
@@ -19,7 +19,20 @@ export interface BlobPutOptions {
   contentType?: string;
   /** Default: `"public"`. Public blobs get a CDN URL; private requires auth. */
   visibility?: BlobVisibility;
-  /** When true, the returned URL includes a content-hash suffix — overwrites produce distinct URLs. Forces sha256 computation. */
+  /**
+   * Default (v1.45+): `true`. Returns an `AssetRef` with `cdnUrl` populated
+   * and the `scriptTag()` / `linkTag()` / `imgTag()` emitters working —
+   * this is the agent-DX flow (paste-and-go HTML with SRI baked in).
+   *
+   * Cost: one SHA-256 pass over the bytes on the client side. For small
+   * assets (the typical case — images, JS, CSS, fonts, JSON < 1 MB) it's
+   * a few ms dominated by network. Pass `false` to skip the SHA pass for
+   * very large uploads where you specifically don't need a content-hashed
+   * URL or SRI.
+   *
+   * When `false`, the returned `AssetRef` has `cdnUrl: null`, `sri: null`,
+   * and the tag emitters throw with an "immutable: true required" hint.
+   */
   immutable?: boolean;
 }
 
@@ -130,32 +143,54 @@ export interface AssetRef {
    * URL + Subresource Integrity + `crossorigin`. The browser will refuse
    * to execute the script if the bytes don't match the SHA.
    *
+   * **Defaults:** `defer: true`. Modern best practice — non-render-
+   * blocking when placed in `<head>` and a no-op at end of `<body>`.
+   * Pass `{ defer: false }` for the rare case requiring sync execution.
+   * `async: true` overrides defer (the two are mutually exclusive).
+   *
    * @example
-   *   const asset = await client.blobs.put(p, "app.js", { content }, { immutable: true });
+   *   const asset = await client.blobs.put(p, "app.js", { content });
    *   html += asset.scriptTag();
-   *   // → <script src="https://pr-abc.run402.com/_blob/app-3a7fc02e.js" integrity="sha256-…" crossorigin></script>
+   *   // → <script src="https://pr-abc.run402.com/_blob/app-3a7fc02e.js" defer integrity="sha256-…" crossorigin></script>
+   *
+   *   asset.scriptTag({ type: "module" });
+   *   // → <script src="…" type="module" defer integrity="…" crossorigin></script>
    */
   scriptTag(opts?: { type?: "module" | "text/javascript"; defer?: boolean; async?: boolean }): string;
 
   /**
    * Returns a ready-to-paste `<link>` tag (default `rel="stylesheet"`)
-   * with content-addressed URL + SRI + `crossorigin`.
+   * with content-addressed URL + SRI + `crossorigin`. `crossorigin` is
+   * always emitted — required for SRI to actually be enforced (also
+   * required for rel="preload" to dedupe with the matching fetch).
    *
    * @example
-   *   asset.linkTag();                       // stylesheet by default
+   *   asset.linkTag();                            // stylesheet
    *   asset.linkTag({ rel: "preload", as: "font" });
+   *   asset.linkTag({ rel: "modulepreload" });
    */
   linkTag(opts?: { rel?: string; as?: string }): string;
 
   /**
    * Returns a ready-to-paste `<img>` tag with the content-addressed URL.
-   * `alt` is the image's accessibility text (default `""`). Browsers don't
-   * support SRI on `<img>`, so no `integrity` attribute is emitted —
-   * integrity is still verifiable by reading `Content-Digest` server-side.
+   *
+   * **Defaults:** `loading="lazy"` + `decoding="async"`. Modern best
+   * practice — lazy loads below-fold images on demand, async decoding
+   * moves the decode off the main thread. Both are baseline-supported
+   * in all major browsers. Agents who specifically need an above-fold
+   * eager image can wrap the result and override.
+   *
+   * Browsers don't support SRI on `<img>`, so no `integrity` attribute
+   * is emitted. The URL is content-hashed so it's still stable across
+   * re-deploys; for byte-level verification, read `Content-Digest`
+   * server-side.
+   *
+   * `alt` is the image's accessibility text (default `""` for decorative
+   * images). Pass a description when the image conveys information.
    *
    * @example
    *   asset.imgTag("Company logo")
-   *   // → <img src="https://pr-abc.run402.com/_blob/logo-a1b2c3d4.png" alt="Company logo">
+   *   // → <img src="https://pr-abc.run402.com/_blob/logo-a1b2c3d4.png" alt="Company logo" loading="lazy" decoding="async">
    */
   imgTag(alt?: string): string;
 }
