@scalemule/news-publication 0.0.79 → 0.0.80

package/README.md

@@ -338,6 +338,45 @@ The platform contract and a complete example live in
 `docs/news-platform/ARTICLE-WORKFLOW-V1.md` in the ScaleMule meta-repo.
 Do not use direct SQL, S3 paths, base64 bodies or invented media readiness.
 
+### Replace a published article photo from a local file
+
+```sh
+npx --yes --package @scalemule/news-publication@0.0.80 scalemule-article replace-photo \
+  --url "$ARTICLE_URL" --file ./venue-exterior.jpg \
+  --metadata ./photo.json --operation-key venue-exterior-v1
+```
+
+Use the normal authorized member's `SCALEMULE_API_KEY` and
+`SCALEMULE_ACCESS_TOKEN`. The caller needs developer-level asset access and
+publication approval rights. Supply caption, credit, factual alt, confirmed rights,
+explicit `aiGenerated` and `label` (null for an ordinary photo) in `photo.json`.
+The URL resolves the authorized publication and article; no UUID search or
+publication build is needed. This does not find a photo or establish rights.
+
+`uploadAndReplacePublishedCover` implements the same operation for applications.
+It transfers bytes through managed Storage, preserves private capture evidence,
+waits for a clean scan, registers Photo, prepares the publication's lead,
+thumbnail and social renditions, reads measured delivery receipts and performs
+one article-version-fenced media write. It verifies unchanged text/audio and,
+when given `--url`, checks the selected lead and social URLs in the public HTML.
+It requires the deployed content-first document and member Photo endpoints.
+
+A private atomic checkpoint lives under `~/.scalemule/newsroom/operations`
+(or `--state PATH`). Keep it: it contains a temporary upload credential until
+completion. Reuse the same file, metadata and operation key after interruption.
+A completed replay verifies the same attachment without uploading or writing
+again. A concurrent article change stops instead of overwriting the editor.
+The default per-run deadline is 30 seconds, adjustable with `--timeout-ms` up to
+120 seconds; timeouts name the blocked stage and preserve progress. Exit 2 means
+API attachment succeeded but public HTML visibility is still pending. A timeout
+is not a success receipt. This is local resumability, not a distributed
+exactly-once service or a guaranteed image-processing SLA.
+
+This published-cover convenience lane stops before upload for collaboration
+articles. Their immutable revision, approval and release gates still apply.
+Animated GIF/APNG/WebP and videos use the Video workflow; this lane accepts
+still JPEG, PNG and WebP up to 25 MiB.
+
 ### Replace an existing, prepared cover
 
 For a legacy published article and an already public, scanned Photo asset,

package/bin/scalemule-article.mjs

@@ -1,16 +1,31 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, rename, open, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { PublicationArticleClient } from '../dist/article-workflow-client.js';
+import { PublicationArticleClient, articlePhotoHtmlMatches } from '../dist/article-workflow-client.js';
 
 const help = `Usage:
   scalemule-article inspect --publication ID --article ID
   scalemule-article replace-cover --publication ID --article ID --file-id ID --expected-version N --metadata photo.json
+  scalemule-article replace-photo --url ARTICLE_URL --file PHOTO --metadata photo.json --operation-key KEY
 
 Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized member).
 Platform admins may use their normal access token with --application-id ID.
 Optional --api-url URL defaults to https://api.scalemule.com.
 
+replace-photo accepts a local file and uses normal member/API-key credentials.
+It requires developer-level asset access and publication approval rights.
+It resolves the publication from its authorized API inventory, saves a private
+upload checkpoint, resumes the same multipart part, waits for scan and measured
+publication renditions, then attaches with the original article version fence.
+It verifies article invariants and, with --url, the public page. The default
+deadline is 30 seconds per run; a failure names its stage and preserves progress.
+Reuse the same --operation-key, metadata and file when resuming. Optional
+--state PATH and --timeout-ms N (maximum 120000). Review-managed articles stop
+before uploading and require their existing exact-revision editorial workflow.
+
 replace-cover selects an already public, scanned Photo asset. It reads measured
 hero and social renditions, preserves the article text, and changes media with
 the supplied version fence. It never uploads raw bytes, republishes the story,
@@ -29,13 +44,35 @@ that every website/CDN cache already displays the new image.
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true, strict: true,
-    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
+    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
   });
   if (values.help || !positionals.length) {
     console.log(help);
   } else {
     const [command, ...extra] = positionals;
-    if (extra.length || !['inspect', 'replace-cover'].includes(command)) throw Error('Use inspect or replace-cover; see --help');
+    const commandStarted = performance.now();
+    const budget = Number(values['timeout-ms'] ?? 30000);
+    if (!Number.isFinite(budget) || budget < 100 || budget > 120000) throw Error('--timeout-ms must be between 100 and 120000');
+    const remaining = () => { const ms = Math.floor(budget - (performance.now()-commandStarted)); if (ms < 1) throw Error('Operation deadline reached; resume the same operation'); return ms; };
+    if (extra.length || !['inspect', 'replace-cover', 'replace-photo'].includes(command)) throw Error('Use inspect, replace-cover or replace-photo; see --help');
+    if (values.url) {
+      if (!process.env.SCALEMULE_API_KEY || !process.env.SCALEMULE_ACCESS_TOKEN || values['application-id']) throw Error('URL resolution requires normal publication member/API-key credentials');
+      const url = new URL(values.url);
+      if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw Error('Use the public HTTPS article URL, without a private review key');
+      const api = values['api-url'] ?? 'https://api.scalemule.com';
+      const apiOrigin = new URL(api); if (apiOrigin.protocol !== 'https:' || apiOrigin.username || apiOrigin.password) throw Error('Use an HTTPS platform API endpoint');
+      const headers = { 'x-api-key': process.env.SCALEMULE_API_KEY, authorization: 'Bearer '+process.env.SCALEMULE_ACCESS_TOKEN };
+      const get = async route => { const r = await fetch(api.replace(/\/$/,'')+route,{headers,redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(10000,remaining()))}); const v = await r.json(); if (!r.ok || !v.success) throw Error(`Article resolution HTTP ${r.status}`); return v.data; };
+      const pubs = await get('/v1/blog/publications');
+      const pub = pubs.items?.find(p=>new URL(p.canonical_url).origin===url.origin);
+      if (!pub) throw Error('The caller has no publication grant for that article origin');
+      const match = /^\/news\/([^/]+)\/?$/.exec(url.pathname);
+      if (!match) throw Error('Use the publication article slug URL');
+      const resolved = await get(`/v1/blog/publications/${encodeURIComponent(pub.id)}/article-content/${encodeURIComponent(decodeURIComponent(match[1]))}`);
+      if (!resolved.article?.id) throw Error('No published article at this URL');
+      if ((values.publication && values.publication !== pub.id) || (values.article && values.article !== resolved.article.id)) throw Error('Article URL and supplied IDs disagree');
+      values.publication = pub.id; values.article = resolved.article.id;
+    }
     for (const key of ['publication', 'article']) if (!values[key]) throw Error(`Missing --${key}`);
     if (!process.env.SCALEMULE_ACCESS_TOKEN) throw Error('SCALEMULE_ACCESS_TOKEN is required; use normal member or platform admin authorization');
     if (!values['application-id'] && !process.env.SCALEMULE_API_KEY) throw Error('Member calls also require SCALEMULE_API_KEY');
@@ -62,6 +99,73 @@ try {
         capabilities: options.capabilities, narration: processing.narration,
         assets: processing.assets, collaboration, elapsed_ms: Math.round(performance.now() - started),
       }, null, 2));
+    } else if (command === 'replace-photo') {
+      for (const key of ['file','metadata','operation-key']) if (!values[key]) throw Error(`Missing --${key}`);
+      if (values['application-id']) throw Error('Local-photo intake uses normal publication member credentials');
+      const metadata = JSON.parse(await readFile(values.metadata,'utf8'));
+      for (const key of ['caption','credit','alt']) if (typeof metadata[key] !== 'string') throw Error(`photo.json requires a string ${key}`);
+      const key = createHash('sha256').update(JSON.stringify([values['api-url']??'https://api.scalemule.com',values.publication,values.article,values['operation-key']])).digest('hex');
+      const statePath = values.state ?? join(homedir(),'.scalemule','newsroom','operations',key+'.json');
+      await mkdir(dirname(statePath),{recursive:true,mode:0o700});
+      const lockPath = statePath+'.lock';
+      let lock;
+      try { lock = await open(lockPath,'wx',0o600); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        const pid = Number(await readFile(lockPath,'utf8'));
+        if (!Number.isSafeInteger(pid) || pid < 1) throw Error('Operation lock is invalid; inspect '+lockPath);
+        let alive = true; try { process.kill(pid,0); } catch (e) { if (e.code === 'ESRCH') alive = false; else throw e; }
+        if (alive) throw Error('This operation is already running; use its existing result');
+        await unlink(lockPath); lock = await open(lockPath,'wx',0o600);
+      }
+      await lock.writeFile(String(process.pid)); await lock.close();
+      try {
+        let checkpoint;
+        try { checkpoint = JSON.parse(await readFile(statePath,'utf8')); } catch(error) { if (error.code !== 'ENOENT') throw error; }
+        const expectedVersion = Number(values['expected-version'] ?? checkpoint?.expectedVersion ?? (await client.processing(values.article,AbortSignal.timeout(remaining()))).version);
+        const bytes = await readFile(values.file);
+        const saveCheckpoint = async state => { const temp = statePath+'.'+process.pid+'.tmp'; await writeFile(temp,JSON.stringify(state),{mode:0o600}); await rename(temp,statePath); checkpoint = state; };
+        const result = await client.uploadAndReplacePublishedCover({
+          articleId:values.article, expectedVersion, operationKey:values['operation-key'],file:new Blob([bytes]),filename:basename(values.file),
+          caption:metadata.caption,credit:metadata.credit,alt:metadata.alt,rightsConfirmed:metadata.rightsConfirmed,aiGenerated:metadata.aiGenerated,label:metadata.label,focalPoint:metadata.focalPoint,
+          checkpoint,saveCheckpoint,timeoutMs:remaining(),
+          onProgress:event=>console.error(JSON.stringify(event)),
+        });
+        if (values.url) {
+          let visible = false;
+          let failure;
+          try {
+            const images = [checkpoint?.payload?.cover_image_url, checkpoint?.payload?.og_image_url];
+            const leads = new Set([images[0],...(checkpoint?.payload?.cover_image?.variants??[]).map(v=>v.url)].filter(Boolean));
+            while (!visible) {
+              const response = await fetch(values.url,{redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(10000,remaining()))});
+              const html = await response.text();
+              visible = response.ok && images.every(Boolean) && articlePhotoHtmlMatches(html,[...leads],images[1]);
+              if (!visible) {
+                // Sites may select another measured responsive rendition of the
+                // same Photo. Read that evidence; never infer a CDN path or ID.
+                await Promise.all(['image/webp','image/jpeg','image/avif'].map(async accept=>{
+                  const api=(values['api-url']??'https://api.scalemule.com').replace(/\/$/,'');
+                  const r=await fetch(api+'/v1/photos/public/'+encodeURIComponent(result.file_id)+'/manifest?preset=hero',{headers:{accept},redirect:'error',signal:AbortSignal.timeout(Math.min(5000,remaining()))});
+                  const value=await r.json();
+                  if(!r.ok || !value.success || value.data?.file_id!==result.file_id) return;
+                  for(const v of Object.values(value.data.variant_metadata??{})) {
+                    if(!Number.isInteger(v.width)||v.width<1||!Number.isInteger(v.height)||v.height<1) continue;
+                    const u=new URL(v.url);
+                    if(u.protocol==='https:'&&!u.username&&!u.password&&!u.search&&!u.hash) leads.add(v.url);
+                  }
+                }));
+                visible = response.ok && images.every(Boolean) && articlePhotoHtmlMatches(html,[...leads],images[1]);
+              }
+              if (!visible) await new Promise(resolve=>setTimeout(resolve,Math.min(500,remaining())));
+            }
+          } catch(error) { failure = error.message; }
+          if (!visible) {
+            console.error(JSON.stringify({...result,state:'attached_public_verification_pending',stage:'public_page',message:'The API attachment is verified; public HTML visibility remains pending. Resume this same operation.',reason:failure}));
+            process.exitCode = 2;
+          } else console.log(JSON.stringify({...result,public_page_verified:true,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        } else console.log(JSON.stringify(result,null,2));
+      } finally { await unlink(lockPath); }
     } else {
       for (const key of ['file-id', 'expected-version', 'metadata']) if (!values[key]) throw Error(`Missing --${key}`);
       const metadata = JSON.parse(await readFile(values.metadata, 'utf8'));
@@ -78,6 +182,6 @@ try {
     }
   }
 } catch (error) {
-  console.error(JSON.stringify({ error: error.message, status: error.status }));
+  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId }));
   process.exitCode = 1;
 }

package/dist/{article-presentation-BrNCcF-5.d.cts → article-presentation-0d1FiDgA.d.cts}

@@ -18,4 +18,4 @@ declare function articlePresentation(value?: ArticlePresentation | null): Articl
 declare function articleHeroRatio(layout: ArticleLayout): number;
 declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
 
-export { type ArticleFormat as A, type ArticleLayout as a, type ArticlePresentation as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };

package/dist/{article-presentation-BrNCcF-5.d.ts → article-presentation-0d1FiDgA.d.ts}

@@ -18,4 +18,4 @@ declare function articlePresentation(value?: ArticlePresentation | null): Articl
 declare function articleHeroRatio(layout: ArticleLayout): number;
 declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
 
-export { type ArticleFormat as A, type ArticleLayout as a, type ArticlePresentation as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };

package/dist/article-workflow-client.cjs

@@ -1,5 +1,292 @@
 'use strict';
 
+// src/article-photo-verification.ts
+function articlePhotoHtmlMatches(html, lead, social) {
+  const contains = (tag, url) => tag.includes(url) || tag.includes(encodeURIComponent(url));
+  const leads = Array.isArray(lead) ? lead : [lead];
+  const image = [...html.matchAll(/<img\b[^>]*>/giu)].some(([tag]) => leads.some((url) => contains(tag, url)));
+  const openGraph = [...html.matchAll(/<meta\b[^>]*>/giu)].some(([tag]) => {
+    const attrs = Object.fromEntries([...tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/gu)].map((m) => [m[1].toLowerCase(), m[2] ?? m[3]]));
+    return (attrs.property ?? attrs.name)?.toLowerCase() === "og:image" && attrs.content === social;
+  });
+  return image && openGraph;
+}
+
+// src/article-photo-operation.ts
+var ArticlePhotoOperationError = class extends Error {
+  constructor(code, stage, message, fileId, status) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.fileId = fileId;
+    this.status = status;
+    this.name = "ArticlePhotoOperationError";
+  }
+  code;
+  stage;
+  fileId;
+  status;
+};
+var digest = async (value) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", value))].map((v) => v.toString(16).padStart(2, "0")).join("");
+var hash = (value) => digest(new TextEncoder().encode(JSON.stringify(value)));
+var canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])])) : v;
+var stableArticle = (p) => [
+  p.id,
+  p.slug,
+  p.title,
+  p.subtitle,
+  p.content_markdown,
+  p.content_html,
+  p.status,
+  p.visibility,
+  p.published_at,
+  p.author_user_id,
+  p.audio_file_id,
+  Object.fromEntries(Object.entries(p.metadata ?? {}).filter(([k]) => !["cover_image", "open_graph_image", "visual_desk_receipt"].includes(k)).sort(([a], [b]) => a.localeCompare(b)))
+];
+function photoType(bytes) {
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+    return "image/jpeg";
+  const ascii = (n, length) => String.fromCharCode(...bytes.subarray(n, n + length));
+  const png = ascii(0, 8) === "\x89PNG\r\n\n";
+  const webp = ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP";
+  if (!png && !webp)
+    throw Error("Use a still JPEG, PNG or WebP photo; animations use the Video workflow");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let n = png ? 8 : 12, chunks = 0; n < bytes.length; chunks++) {
+    if (chunks >= 1e4 || n + 8 > bytes.length)
+      throw Error("Invalid or truncated photo container");
+    const kind = ascii(png ? n + 4 : n, 4);
+    if (["acTL", "ANIM", "ANMF"].includes(kind))
+      throw Error("Animated photos require the Video workflow");
+    const size = view.getUint32(png ? n : n + 4, webp);
+    n += size + (png ? 12 : 8 + size % 2);
+    if (n > bytes.length)
+      throw Error("Truncated photo container");
+    if (png && kind === "IEND")
+      break;
+  }
+  return png ? "image/png" : "image/webp";
+}
+function immutableUrl(raw) {
+  try {
+    const u = new URL(String(raw));
+    return u.protocol === "https:" && !u.username && !u.password && !u.search && !u.hash;
+  } catch {
+    return false;
+  }
+}
+var measured = (m, file) => m?.ready === true && m.file_id === file && immutableUrl(m.url) && Number.isInteger(m.width) && m.width > 0 && m.width <= 12e3 && Number.isInteger(m.height) && m.height > 0 && m.height <= 12e3;
+var mediaMatches = (post, payload) => post.cover_image_url === payload.cover_image_url && post.og_image_url === payload.og_image_url && JSON.stringify(canonical(post.metadata?.cover_image)) === JSON.stringify(canonical(payload.cover_image)) && JSON.stringify(canonical(post.metadata?.open_graph_image)) === JSON.stringify(canonical(payload.open_graph_image));
+async function runArticlePhoto(t, input) {
+  const started = performance.now();
+  if (!input.operationKey || input.operationKey.length > 128 || !Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 1 || input.rightsConfirmed !== true || !input.alt?.trim() || typeof input.aiGenerated !== "boolean" || input.aiGenerated && !input.label?.trim())
+    throw Error("Supply a stable operation key, current article version, confirmed rights, factual alt and explicit provenance");
+  if (typeof input.caption !== "string" || typeof input.credit !== "string" || !(input.label === null || typeof input.label === "string"))
+    throw Error("Supply explicit caption, credit and provenance label");
+  for (const [name, value, limit] of [["caption", input.caption, 2e3], ["credit", input.credit, 8e3], ["alt", input.alt, 1e3], ["label", input.label ?? "", 200]]) {
+    if ([...value].length > limit) throw Error(`Photo ${name} exceeds ${limit} characters`);
+  }
+  const focal = input.focalPoint ?? { x: 0.5, y: 0.5 };
+  if (![focal.x, focal.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+    throw Error("Focal point must be within the image");
+  if (!input.file.size || input.file.size > 25 * 1024 * 1024)
+    throw Error("A photo must be between 1 byte and 25 MiB");
+  const bytes = new Uint8Array(await input.file.arrayBuffer());
+  const mime = photoType(bytes);
+  const identity = await hash([t.publicationId, input.articleId, input.operationKey, await digest(bytes), input.expectedVersion, input.caption, input.credit, input.alt, input.rightsConfirmed, input.aiGenerated, input.label, input.focalPoint ?? { x: 0.5, y: 0.5 }]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity))
+    throw new ArticlePhotoOperationError("OPERATION_CONFLICT", "validation", "The saved operation belongs to different input; do not overwrite it");
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : void 0;
+  let stage = "preflight";
+  const deadline = AbortSignal.timeout(Math.min(Math.max(input.timeoutMs ?? 3e4, 100), 12e4));
+  const request = (path, method, body) => t.request(path, method, body, void 0, deadline);
+  const progress = async (next) => {
+    stage = next;
+    if (state) {
+      state.stage = next;
+      await input.saveCheckpoint(structuredClone(state));
+    }
+    input.onProgress?.({ stage, elapsed_ms: Math.round(performance.now() - started), file_id: state?.fileId });
+  };
+  const sleep = () => new Promise((resolve, reject) => {
+    deadline.throwIfAborted();
+    const id = setTimeout(() => {
+      deadline.removeEventListener("abort", abort);
+      resolve();
+    }, 300);
+    const abort = () => {
+      clearTimeout(id);
+      reject(deadline.reason);
+    };
+    deadline.addEventListener("abort", abort, { once: true });
+  });
+  const postPath = `/articles/${encodeURIComponent(input.articleId)}/document`;
+  try {
+    const [post, options, collaboration, policy] = await Promise.all([
+      request(postPath),
+      request(`/article-workflow/options?article_id=${encodeURIComponent(input.articleId)}`),
+      request(`/articles/${encodeURIComponent(input.articleId)}/collaboration`).then(() => true).catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return false;
+        throw error;
+      }),
+      request(`/v1/photos/policies/article/editor?publication_id=${encodeURIComponent(t.publicationId)}`)
+    ]);
+    if (post.status !== "published" || post.visibility !== "public" || options.workflow_version !== 1)
+      throw new ArticlePhotoOperationError("ARTICLE_NOT_PUBLIC", stage, "Select a currently published public article");
+    if (collaboration)
+      throw new ArticlePhotoOperationError("REVISION_WORKFLOW_REQUIRED", stage, "This story requires an immutable media revision and editorial release; no upload or public mutation was made");
+    if (state?.payload && mediaMatches(post, state.payload)) {
+      if (await hash(stableArticle(post)) !== state.articleHash)
+        throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The photo is attached, but other article content changed; inspect before continuing", state.fileId);
+      state.attachedVersion = post.version;
+      await progress("verified");
+      return { article_id: input.articleId, file_id: state.fileId, version: post.version, state: "already_applied", elapsed_ms: Math.round(performance.now() - started) };
+    }
+    if (post.version !== input.expectedVersion)
+      throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The article version changed; existing text and media were preserved", state?.fileId);
+    const articleHash = await hash(stableArticle(post));
+    if (state && state.articleHash !== articleHash)
+      throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The article changed while the operation was paused", state.fileId);
+    state ??= { version: 1, identity, stage, expectedVersion: input.expectedVersion, articleHash };
+    await progress("upload");
+    if (!state.etag) {
+      const filename = `article-${identity}.${mime === "image/jpeg" ? "jpg" : mime.split("/")[1]}`;
+      const reservation = await request("/v1/storage/signed-url/multipart/start", "POST", {
+        filename,
+        content_type: mime,
+        size_bytes: bytes.length,
+        visibility: "anonymous_visible",
+        chunk_size: 25 * 1024 * 1024,
+        client_upload_key: identity,
+        metadata: { purpose: "article-photo", publication_id: t.publicationId, article_id: input.articleId, operation_hash: identity, caption: input.caption, credit: input.credit, alt: input.alt, rights_confirmed: true, ai_generated: input.aiGenerated, label: input.label }
+      });
+      if (state.fileId && state.fileId !== reservation.file_id || reservation.total_parts !== 1)
+        throw new ArticlePhotoOperationError("UPLOAD_SESSION_CHANGED", stage, "The original upload session expired or changed; no duplicate attachment was attempted", state.fileId);
+      state.fileId = reservation.file_id;
+      state.sessionId = reservation.upload_session_id;
+      state.completionToken = reservation.completion_token;
+      await progress("upload");
+      const info = await request(`/v1/storage/files/${state.fileId}/info`);
+      if (info.filename !== filename)
+        throw new ArticlePhotoOperationError("UPLOAD_IDENTITY_MISMATCH", stage, "The upload session does not match these source bytes", state.fileId);
+      const part = reservation.part_urls?.find((p) => p.part_number === 1);
+      const u = new URL(part?.url);
+      if (u.protocol !== "https:" || u.username || u.password)
+        throw Error("Invalid managed upload destination");
+      const response = await t.fetch(u, { method: "PUT", body: input.file, redirect: "error", signal: deadline });
+      const etag = response.headers.get("etag");
+      await response.body?.cancel();
+      if (!response.ok || !etag)
+        throw Error("Managed upload did not acknowledge its part; resume this operation");
+      state.etag = etag;
+      await progress("complete");
+    }
+    if (!state.completed) {
+      await request("/v1/storage/signed-url/multipart/complete", "POST", { file_id: state.fileId, upload_session_id: state.sessionId, completion_token: state.completionToken, parts: [{ part_number: 1, etag: state.etag }] });
+      state.completed = true;
+      delete state.completionToken;
+      await progress("scan");
+    }
+    for (; ; ) {
+      const status = await request(`/v1/storage/files/${state.fileId}/status`);
+      if (["threat", "quarantined", "error"].includes(status.scan?.status))
+        throw new ArticlePhotoOperationError("SCAN_REJECTED", stage, "Storage did not clear this image; the previous cover remains", state.fileId);
+      if (status.scan?.status === "clean" && status.urls?.cdn_url)
+        break;
+      await sleep();
+    }
+    await progress("photo");
+    const batched = policy.capabilities?.batched_article_renditions === true;
+    let prepared;
+    if (!state.registered || batched) {
+      if (batched) await progress("renditions");
+      const registered = await request("/v1/photos/register", "POST", { file_id: state.fileId, content_kind: "article", role: "lead", publication_id: t.publicationId, prepare_article_renditions: batched });
+      if (batched && registered.prepared_article_renditions !== true) throw Error("Photo did not confirm the measured rendition batch; resume the same upload");
+      prepared = batched ? registered : void 0;
+      state.registered = true;
+      await progress("renditions");
+    }
+    const source = prepared?.source ?? await request(`/v1/photos/public/${state.fileId}/manifest?preset=hero`);
+    if (source.file_id !== state.fileId || !Number.isInteger(source.width) || source.width <= 0)
+      throw Error("Photo source identity or measured dimensions are missing");
+    const requirements = ["lead", "thumbnail", "social"].flatMap((role) => {
+      const specs = policy.roles?.[role]?.renditions;
+      if (!Array.isArray(specs) || !specs.length)
+        throw Error("Publication Photo policy is incomplete");
+      return specs.filter((r) => r.fit !== "scaledown" || r.width <= source.width).map((spec) => ({ role, spec }));
+    });
+    if (!requirements.length || requirements.length > 48)
+      throw Error("Publication Photo policy exceeds operation limits");
+    const outputs = [];
+    const preparations = /* @__PURE__ */ new Map();
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(4, requirements.length) }, async () => {
+      while (next < requirements.length) {
+        const { role, spec: r } = requirements[next++];
+        if (!Number.isInteger(r.width) || r.width < 1 || r.width > 12e3 || !["cover", "contain", "scaledown"].includes(r.fit) || !["jpeg", "webp", "avif"].includes(r.format) || !Number.isInteger(r.quality) || r.quality < 1 || r.quality > 100 || r.height != null && (!Number.isInteger(r.height) || r.height < 1 || r.height > 12e3))
+          throw Error("Invalid publication Photo policy");
+        const key = `w${r.width}_h${r.height ?? 0}_${r.fit}_q${r.quality}_${r.format}`;
+        let preparation = preparations.get(key);
+        if (!preparation) {
+          preparation = (async () => {
+            const path = `/v1/photos/public/${state.fileId}/manifest?rendition=${key}`;
+            let receipt2 = batched ? prepared?.article_renditions?.find((v) => v.key === key && v.role === role && v.format === r.format) : await request(path);
+            if (batched && !measured(receipt2, state.fileId)) throw Error("Photo batch is missing a required measured receipt; resume the same uploaded file");
+            if (!measured(receipt2, state.fileId)) {
+              const q = new URLSearchParams({ width: String(r.width), fit: r.fit, quality: String(r.quality), format: r.format });
+              if (r.height)
+                q.set("height", String(r.height));
+              const response = await t.fetch(new URL(t.apiUrl.replace(/\/$/, "") + `/v1/photos/public/${state.fileId}/transform?${q}`), { method: "GET", redirect: "manual", signal: deadline });
+              const ok = response.ok && response.headers.get("content-type")?.startsWith("image/") || [302, 303, 307, 308].includes(response.status);
+              await response.body?.cancel();
+              if (!ok)
+                throw Error("Photo could not prepare a required rendition");
+              while (!measured(receipt2, state.fileId)) {
+                receipt2 = await request(path);
+                if (!measured(receipt2, state.fileId))
+                  await sleep();
+              }
+            }
+            return receipt2;
+          })();
+          preparations.set(key, preparation);
+        }
+        const receipt = await preparation;
+        outputs.push({ role, file_id: state.fileId, url: receipt.url, width: receipt.width, height: receipt.height, format: r.format });
+      }
+    }));
+    const leads = outputs.filter((o) => o.role === "lead").sort((a, b) => a.width - b.width || a.format.localeCompare(b.format));
+    const master = [...leads].reverse().find((o) => o.format === "webp") ?? leads.at(-1);
+    const social = outputs.find((o) => o.role === "social" && o.format === "jpeg") ?? outputs.find((o) => o.role === "social");
+    if (!master || !social || leads.length > 20)
+      throw Error("Photo policy has no usable lead or social output");
+    state.payload = {
+      expected_version: state.expectedVersion,
+      cover_image_url: master.url,
+      og_image_url: social.url,
+      cover_image: { file_id: state.fileId, master_url: master.url, width: master.width, height: master.height, aspect_ratio: `${master.width}:${master.height}`, alt: input.alt, caption: input.caption, attribution: input.credit, ai_generated: input.aiGenerated, label: input.label, focal_point: input.focalPoint ?? { x: 0.5, y: 0.5 }, variants: leads.map(({ url, width, height, format }) => ({ url, width, height, format })) },
+      open_graph_image: { file_id: state.fileId, url: social.url, width: social.width, height: social.height, aspect_ratio: `${social.width}:${social.height}` }
+    };
+    await progress("attach");
+    const result = await request(`/articles/${encodeURIComponent(input.articleId)}/media`, "PUT", state.payload);
+    state.attachedVersion = result.version;
+    await progress("verify");
+    const after = await request(postPath);
+    if (!mediaMatches(after, state.payload) || await hash(stableArticle(after)) !== state.articleHash)
+      throw new ArticlePhotoOperationError("VERIFICATION_CONFLICT", stage, "The current article differs from this operation; inspect it before making another change", state.fileId);
+    await progress("verified");
+    return { article_id: input.articleId, file_id: state.fileId, version: after.version, state: "verified", elapsed_ms: Math.round(performance.now() - started) };
+  } catch (error) {
+    if (error instanceof ArticlePhotoOperationError)
+      throw error;
+    const status = typeof error?.status === "number" ? error.status : void 0;
+    const code = deadline.aborted ? "DEADLINE_EXCEEDED" : status === 409 && stage === "attach" ? "ARTICLE_CHANGED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : "STEP_FAILED";
+    throw new ArticlePhotoOperationError(code, stage, deadline.aborted ? "Operation reached its time limit; resume the same operation and checkpoint. Success was not asserted." : error instanceof Error ? error.message : "Article photo operation failed", state?.fileId, status);
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -21,7 +308,7 @@ var PublicationArticleClient = class {
   }
   config;
   base;
-  async request(path, method = "GET", body, extra) {
+  async request(path, method = "GET", body, extra, signal) {
     const headers = new Headers(extra);
     headers.set("accept", "application/json");
     if (this.config.apiKey) headers.set("x-api-key", this.config.apiKey);
@@ -39,7 +326,7 @@ var PublicationArticleClient = class {
       method,
       headers,
       body: body === void 0 ? void 0 : form ? body : JSON.stringify(body),
-      signal: AbortSignal.timeout(form ? 9e4 : 3e4),
+      signal: signal ?? AbortSignal.timeout(form ? 9e4 : 3e4),
       cache: "no-store",
       redirect: "error"
     });
@@ -72,11 +359,18 @@ var PublicationArticleClient = class {
       `/articles/${encodeURIComponent(articleId)}/collaboration`
     );
   }
-  processing(articleId) {
+  processing(articleId, signal) {
     return this.request(
-      `/articles/${encodeURIComponent(articleId)}/processing`
+      `/articles/${encodeURIComponent(articleId)}/processing`,
+      void 0,
+      void 0,
+      void 0,
+      signal
     );
   }
+  uploadAndReplacePublishedCover(input) {
+    return runArticlePhoto({ publicationId: this.config.publicationId, apiUrl: this.config.apiUrl, fetch: this.config.fetch ?? fetch, request: this.request.bind(this) }, input);
+  }
   /** Replace a legacy publication cover using ready, measured public Photo renditions.
    * This never enrolls a story, publishes text, creates narration or retries a conflict.
    * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -262,7 +556,7 @@ var PublicationArticleClient = class {
       const selected = [];
       for (const asset of input.assets ?? []) {
         let current = await this.get(created.article_id);
-        const digest = Array.from(
+        const digest2 = Array.from(
           new Uint8Array(
             await crypto.subtle.digest(
               "SHA-256",
@@ -271,7 +565,7 @@ var PublicationArticleClient = class {
           )
         ).map((v) => v.toString(16).padStart(2, "0")).join("");
         const existing = current.contributions.find(
-          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest && Object.entries(asset.metadata).every(
+          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest2 && Object.entries(asset.metadata).every(
             ([k, v]) => c.payload[k] === v
           )
         );
@@ -352,7 +646,7 @@ var PublicationArticleClient = class {
   }
 };
 function sameDocument(a, b) {
-  const canonical = (d) => [
+  const canonical2 = (d) => [
     d.title,
     d.subtitle || "",
     d.content_markdown,
@@ -370,8 +664,10 @@ function sameDocument(a, b) {
       m.position
     ])
   ];
-  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+  return JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
 }
 
+exports.ArticlePhotoOperationError = ArticlePhotoOperationError;
 exports.ArticleWorkflowError = ArticleWorkflowError;
 exports.PublicationArticleClient = PublicationArticleClient;
+exports.articlePhotoHtmlMatches = articlePhotoHtmlMatches;

package/dist/article-workflow-client.d.cts

@@ -1,4 +1,45 @@
-import { A as ArticleFormat, a as ArticleLayout } from './article-presentation-BrNCcF-5.cjs';
+import { A as ArticleFormat, b as ArticleLayout } from './article-presentation-0d1FiDgA.cjs';
+
+/** Check rendered image tags, not a URL mentioned only in serialized page data. */
+declare function articlePhotoHtmlMatches(html: string, lead: string | string[], social: string): boolean;
+
+type PhotoOperationCheckpoint = {
+    version: 1;
+    identity: string;
+    stage: string;
+    expectedVersion: number;
+    articleHash: string;
+    fileId?: string;
+    sessionId?: string;
+    completionToken?: string;
+    etag?: string;
+    completed?: boolean;
+    registered?: boolean;
+    payload?: any;
+    attachedVersion?: number;
+};
+type ArticlePhotoInput = Omit<PublishedCoverReplacement, "fileId" | "expectedVersion" | "socialRenditionKey"> & {
+    operationKey: string;
+    expectedVersion: number;
+    file: Blob;
+    filename: string;
+    checkpoint?: PhotoOperationCheckpoint;
+    /** Persist atomically before the next side effect. Contains private upload tokens. */
+    saveCheckpoint: (state: PhotoOperationCheckpoint) => Promise<void>;
+    timeoutMs?: number;
+    onProgress?: (event: {
+        stage: string;
+        elapsed_ms: number;
+        file_id?: string;
+    }) => void;
+};
+declare class ArticlePhotoOperationError extends Error {
+    code: string;
+    stage: string;
+    fileId?: string | undefined;
+    status?: number | undefined;
+    constructor(code: string, stage: string, message: string, fileId?: string | undefined, status?: number | undefined);
+}
 
 type ArticleDocument = {
     title: string;
@@ -104,6 +145,7 @@ type ArticleWorkflowOptions = {
         inline_media_body?: boolean;
         automatic_public_narration?: boolean;
         prioritized_narration_processing?: boolean;
+        content_first_editor_document?: boolean;
     };
 };
 type ArticleOperation = {
@@ -162,7 +204,14 @@ declare class PublicationArticleClient {
         current_revision_id?: string;
     }>;
     get(articleId: string): Promise<Record>;
-    processing(articleId: string): Promise<ArticleProcessing>;
+    processing(articleId: string, signal?: AbortSignal): Promise<ArticleProcessing>;
+    uploadAndReplacePublishedCover(input: ArticlePhotoInput): Promise<{
+        article_id: string;
+        file_id: string | undefined;
+        version: any;
+        state: string;
+        elapsed_ms: number;
+    }>;
     /** Replace a legacy publication cover using ready, measured public Photo renditions.
      * This never enrolls a story, publishes text, creates narration or retries a conflict.
      * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -213,4 +262,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient, type PublishedCoverReplacement };
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articlePhotoHtmlMatches };

package/dist/article-workflow-client.d.ts

@@ -1,4 +1,45 @@
-import { A as ArticleFormat, a as ArticleLayout } from './article-presentation-BrNCcF-5.js';
+import { A as ArticleFormat, b as ArticleLayout } from './article-presentation-0d1FiDgA.js';
+
+/** Check rendered image tags, not a URL mentioned only in serialized page data. */
+declare function articlePhotoHtmlMatches(html: string, lead: string | string[], social: string): boolean;
+
+type PhotoOperationCheckpoint = {
+    version: 1;
+    identity: string;
+    stage: string;
+    expectedVersion: number;
+    articleHash: string;
+    fileId?: string;
+    sessionId?: string;
+    completionToken?: string;
+    etag?: string;
+    completed?: boolean;
+    registered?: boolean;
+    payload?: any;
+    attachedVersion?: number;
+};
+type ArticlePhotoInput = Omit<PublishedCoverReplacement, "fileId" | "expectedVersion" | "socialRenditionKey"> & {
+    operationKey: string;
+    expectedVersion: number;
+    file: Blob;
+    filename: string;
+    checkpoint?: PhotoOperationCheckpoint;
+    /** Persist atomically before the next side effect. Contains private upload tokens. */
+    saveCheckpoint: (state: PhotoOperationCheckpoint) => Promise<void>;
+    timeoutMs?: number;
+    onProgress?: (event: {
+        stage: string;
+        elapsed_ms: number;
+        file_id?: string;
+    }) => void;
+};
+declare class ArticlePhotoOperationError extends Error {
+    code: string;
+    stage: string;
+    fileId?: string | undefined;
+    status?: number | undefined;
+    constructor(code: string, stage: string, message: string, fileId?: string | undefined, status?: number | undefined);
+}
 
 type ArticleDocument = {
     title: string;
@@ -104,6 +145,7 @@ type ArticleWorkflowOptions = {
         inline_media_body?: boolean;
         automatic_public_narration?: boolean;
         prioritized_narration_processing?: boolean;
+        content_first_editor_document?: boolean;
     };
 };
 type ArticleOperation = {
@@ -162,7 +204,14 @@ declare class PublicationArticleClient {
         current_revision_id?: string;
     }>;
     get(articleId: string): Promise<Record>;
-    processing(articleId: string): Promise<ArticleProcessing>;
+    processing(articleId: string, signal?: AbortSignal): Promise<ArticleProcessing>;
+    uploadAndReplacePublishedCover(input: ArticlePhotoInput): Promise<{
+        article_id: string;
+        file_id: string | undefined;
+        version: any;
+        state: string;
+        elapsed_ms: number;
+    }>;
     /** Replace a legacy publication cover using ready, measured public Photo renditions.
      * This never enrolls a story, publishes text, creates narration or retries a conflict.
      * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -213,4 +262,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, PublicationArticleClient, type PublishedCoverReplacement };
+export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articlePhotoHtmlMatches };

package/dist/article-workflow-client.js

@@ -1,3 +1,290 @@
+// src/article-photo-verification.ts
+function articlePhotoHtmlMatches(html, lead, social) {
+  const contains = (tag, url) => tag.includes(url) || tag.includes(encodeURIComponent(url));
+  const leads = Array.isArray(lead) ? lead : [lead];
+  const image = [...html.matchAll(/<img\b[^>]*>/giu)].some(([tag]) => leads.some((url) => contains(tag, url)));
+  const openGraph = [...html.matchAll(/<meta\b[^>]*>/giu)].some(([tag]) => {
+    const attrs = Object.fromEntries([...tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/gu)].map((m) => [m[1].toLowerCase(), m[2] ?? m[3]]));
+    return (attrs.property ?? attrs.name)?.toLowerCase() === "og:image" && attrs.content === social;
+  });
+  return image && openGraph;
+}
+
+// src/article-photo-operation.ts
+var ArticlePhotoOperationError = class extends Error {
+  constructor(code, stage, message, fileId, status) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.fileId = fileId;
+    this.status = status;
+    this.name = "ArticlePhotoOperationError";
+  }
+  code;
+  stage;
+  fileId;
+  status;
+};
+var digest = async (value) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", value))].map((v) => v.toString(16).padStart(2, "0")).join("");
+var hash = (value) => digest(new TextEncoder().encode(JSON.stringify(value)));
+var canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])])) : v;
+var stableArticle = (p) => [
+  p.id,
+  p.slug,
+  p.title,
+  p.subtitle,
+  p.content_markdown,
+  p.content_html,
+  p.status,
+  p.visibility,
+  p.published_at,
+  p.author_user_id,
+  p.audio_file_id,
+  Object.fromEntries(Object.entries(p.metadata ?? {}).filter(([k]) => !["cover_image", "open_graph_image", "visual_desk_receipt"].includes(k)).sort(([a], [b]) => a.localeCompare(b)))
+];
+function photoType(bytes) {
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+    return "image/jpeg";
+  const ascii = (n, length) => String.fromCharCode(...bytes.subarray(n, n + length));
+  const png = ascii(0, 8) === "\x89PNG\r\n\n";
+  const webp = ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP";
+  if (!png && !webp)
+    throw Error("Use a still JPEG, PNG or WebP photo; animations use the Video workflow");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let n = png ? 8 : 12, chunks = 0; n < bytes.length; chunks++) {
+    if (chunks >= 1e4 || n + 8 > bytes.length)
+      throw Error("Invalid or truncated photo container");
+    const kind = ascii(png ? n + 4 : n, 4);
+    if (["acTL", "ANIM", "ANMF"].includes(kind))
+      throw Error("Animated photos require the Video workflow");
+    const size = view.getUint32(png ? n : n + 4, webp);
+    n += size + (png ? 12 : 8 + size % 2);
+    if (n > bytes.length)
+      throw Error("Truncated photo container");
+    if (png && kind === "IEND")
+      break;
+  }
+  return png ? "image/png" : "image/webp";
+}
+function immutableUrl(raw) {
+  try {
+    const u = new URL(String(raw));
+    return u.protocol === "https:" && !u.username && !u.password && !u.search && !u.hash;
+  } catch {
+    return false;
+  }
+}
+var measured = (m, file) => m?.ready === true && m.file_id === file && immutableUrl(m.url) && Number.isInteger(m.width) && m.width > 0 && m.width <= 12e3 && Number.isInteger(m.height) && m.height > 0 && m.height <= 12e3;
+var mediaMatches = (post, payload) => post.cover_image_url === payload.cover_image_url && post.og_image_url === payload.og_image_url && JSON.stringify(canonical(post.metadata?.cover_image)) === JSON.stringify(canonical(payload.cover_image)) && JSON.stringify(canonical(post.metadata?.open_graph_image)) === JSON.stringify(canonical(payload.open_graph_image));
+async function runArticlePhoto(t, input) {
+  const started = performance.now();
+  if (!input.operationKey || input.operationKey.length > 128 || !Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 1 || input.rightsConfirmed !== true || !input.alt?.trim() || typeof input.aiGenerated !== "boolean" || input.aiGenerated && !input.label?.trim())
+    throw Error("Supply a stable operation key, current article version, confirmed rights, factual alt and explicit provenance");
+  if (typeof input.caption !== "string" || typeof input.credit !== "string" || !(input.label === null || typeof input.label === "string"))
+    throw Error("Supply explicit caption, credit and provenance label");
+  for (const [name, value, limit] of [["caption", input.caption, 2e3], ["credit", input.credit, 8e3], ["alt", input.alt, 1e3], ["label", input.label ?? "", 200]]) {
+    if ([...value].length > limit) throw Error(`Photo ${name} exceeds ${limit} characters`);
+  }
+  const focal = input.focalPoint ?? { x: 0.5, y: 0.5 };
+  if (![focal.x, focal.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+    throw Error("Focal point must be within the image");
+  if (!input.file.size || input.file.size > 25 * 1024 * 1024)
+    throw Error("A photo must be between 1 byte and 25 MiB");
+  const bytes = new Uint8Array(await input.file.arrayBuffer());
+  const mime = photoType(bytes);
+  const identity = await hash([t.publicationId, input.articleId, input.operationKey, await digest(bytes), input.expectedVersion, input.caption, input.credit, input.alt, input.rightsConfirmed, input.aiGenerated, input.label, input.focalPoint ?? { x: 0.5, y: 0.5 }]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity))
+    throw new ArticlePhotoOperationError("OPERATION_CONFLICT", "validation", "The saved operation belongs to different input; do not overwrite it");
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : void 0;
+  let stage = "preflight";
+  const deadline = AbortSignal.timeout(Math.min(Math.max(input.timeoutMs ?? 3e4, 100), 12e4));
+  const request = (path, method, body) => t.request(path, method, body, void 0, deadline);
+  const progress = async (next) => {
+    stage = next;
+    if (state) {
+      state.stage = next;
+      await input.saveCheckpoint(structuredClone(state));
+    }
+    input.onProgress?.({ stage, elapsed_ms: Math.round(performance.now() - started), file_id: state?.fileId });
+  };
+  const sleep = () => new Promise((resolve, reject) => {
+    deadline.throwIfAborted();
+    const id = setTimeout(() => {
+      deadline.removeEventListener("abort", abort);
+      resolve();
+    }, 300);
+    const abort = () => {
+      clearTimeout(id);
+      reject(deadline.reason);
+    };
+    deadline.addEventListener("abort", abort, { once: true });
+  });
+  const postPath = `/articles/${encodeURIComponent(input.articleId)}/document`;
+  try {
+    const [post, options, collaboration, policy] = await Promise.all([
+      request(postPath),
+      request(`/article-workflow/options?article_id=${encodeURIComponent(input.articleId)}`),
+      request(`/articles/${encodeURIComponent(input.articleId)}/collaboration`).then(() => true).catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return false;
+        throw error;
+      }),
+      request(`/v1/photos/policies/article/editor?publication_id=${encodeURIComponent(t.publicationId)}`)
+    ]);
+    if (post.status !== "published" || post.visibility !== "public" || options.workflow_version !== 1)
+      throw new ArticlePhotoOperationError("ARTICLE_NOT_PUBLIC", stage, "Select a currently published public article");
+    if (collaboration)
+      throw new ArticlePhotoOperationError("REVISION_WORKFLOW_REQUIRED", stage, "This story requires an immutable media revision and editorial release; no upload or public mutation was made");
+    if (state?.payload && mediaMatches(post, state.payload)) {
+      if (await hash(stableArticle(post)) !== state.articleHash)
+        throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The photo is attached, but other article content changed; inspect before continuing", state.fileId);
+      state.attachedVersion = post.version;
+      await progress("verified");
+      return { article_id: input.articleId, file_id: state.fileId, version: post.version, state: "already_applied", elapsed_ms: Math.round(performance.now() - started) };
+    }
+    if (post.version !== input.expectedVersion)
+      throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The article version changed; existing text and media were preserved", state?.fileId);
+    const articleHash = await hash(stableArticle(post));
+    if (state && state.articleHash !== articleHash)
+      throw new ArticlePhotoOperationError("ARTICLE_CHANGED", stage, "The article changed while the operation was paused", state.fileId);
+    state ??= { version: 1, identity, stage, expectedVersion: input.expectedVersion, articleHash };
+    await progress("upload");
+    if (!state.etag) {
+      const filename = `article-${identity}.${mime === "image/jpeg" ? "jpg" : mime.split("/")[1]}`;
+      const reservation = await request("/v1/storage/signed-url/multipart/start", "POST", {
+        filename,
+        content_type: mime,
+        size_bytes: bytes.length,
+        visibility: "anonymous_visible",
+        chunk_size: 25 * 1024 * 1024,
+        client_upload_key: identity,
+        metadata: { purpose: "article-photo", publication_id: t.publicationId, article_id: input.articleId, operation_hash: identity, caption: input.caption, credit: input.credit, alt: input.alt, rights_confirmed: true, ai_generated: input.aiGenerated, label: input.label }
+      });
+      if (state.fileId && state.fileId !== reservation.file_id || reservation.total_parts !== 1)
+        throw new ArticlePhotoOperationError("UPLOAD_SESSION_CHANGED", stage, "The original upload session expired or changed; no duplicate attachment was attempted", state.fileId);
+      state.fileId = reservation.file_id;
+      state.sessionId = reservation.upload_session_id;
+      state.completionToken = reservation.completion_token;
+      await progress("upload");
+      const info = await request(`/v1/storage/files/${state.fileId}/info`);
+      if (info.filename !== filename)
+        throw new ArticlePhotoOperationError("UPLOAD_IDENTITY_MISMATCH", stage, "The upload session does not match these source bytes", state.fileId);
+      const part = reservation.part_urls?.find((p) => p.part_number === 1);
+      const u = new URL(part?.url);
+      if (u.protocol !== "https:" || u.username || u.password)
+        throw Error("Invalid managed upload destination");
+      const response = await t.fetch(u, { method: "PUT", body: input.file, redirect: "error", signal: deadline });
+      const etag = response.headers.get("etag");
+      await response.body?.cancel();
+      if (!response.ok || !etag)
+        throw Error("Managed upload did not acknowledge its part; resume this operation");
+      state.etag = etag;
+      await progress("complete");
+    }
+    if (!state.completed) {
+      await request("/v1/storage/signed-url/multipart/complete", "POST", { file_id: state.fileId, upload_session_id: state.sessionId, completion_token: state.completionToken, parts: [{ part_number: 1, etag: state.etag }] });
+      state.completed = true;
+      delete state.completionToken;
+      await progress("scan");
+    }
+    for (; ; ) {
+      const status = await request(`/v1/storage/files/${state.fileId}/status`);
+      if (["threat", "quarantined", "error"].includes(status.scan?.status))
+        throw new ArticlePhotoOperationError("SCAN_REJECTED", stage, "Storage did not clear this image; the previous cover remains", state.fileId);
+      if (status.scan?.status === "clean" && status.urls?.cdn_url)
+        break;
+      await sleep();
+    }
+    await progress("photo");
+    const batched = policy.capabilities?.batched_article_renditions === true;
+    let prepared;
+    if (!state.registered || batched) {
+      if (batched) await progress("renditions");
+      const registered = await request("/v1/photos/register", "POST", { file_id: state.fileId, content_kind: "article", role: "lead", publication_id: t.publicationId, prepare_article_renditions: batched });
+      if (batched && registered.prepared_article_renditions !== true) throw Error("Photo did not confirm the measured rendition batch; resume the same upload");
+      prepared = batched ? registered : void 0;
+      state.registered = true;
+      await progress("renditions");
+    }
+    const source = prepared?.source ?? await request(`/v1/photos/public/${state.fileId}/manifest?preset=hero`);
+    if (source.file_id !== state.fileId || !Number.isInteger(source.width) || source.width <= 0)
+      throw Error("Photo source identity or measured dimensions are missing");
+    const requirements = ["lead", "thumbnail", "social"].flatMap((role) => {
+      const specs = policy.roles?.[role]?.renditions;
+      if (!Array.isArray(specs) || !specs.length)
+        throw Error("Publication Photo policy is incomplete");
+      return specs.filter((r) => r.fit !== "scaledown" || r.width <= source.width).map((spec) => ({ role, spec }));
+    });
+    if (!requirements.length || requirements.length > 48)
+      throw Error("Publication Photo policy exceeds operation limits");
+    const outputs = [];
+    const preparations = /* @__PURE__ */ new Map();
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(4, requirements.length) }, async () => {
+      while (next < requirements.length) {
+        const { role, spec: r } = requirements[next++];
+        if (!Number.isInteger(r.width) || r.width < 1 || r.width > 12e3 || !["cover", "contain", "scaledown"].includes(r.fit) || !["jpeg", "webp", "avif"].includes(r.format) || !Number.isInteger(r.quality) || r.quality < 1 || r.quality > 100 || r.height != null && (!Number.isInteger(r.height) || r.height < 1 || r.height > 12e3))
+          throw Error("Invalid publication Photo policy");
+        const key = `w${r.width}_h${r.height ?? 0}_${r.fit}_q${r.quality}_${r.format}`;
+        let preparation = preparations.get(key);
+        if (!preparation) {
+          preparation = (async () => {
+            const path = `/v1/photos/public/${state.fileId}/manifest?rendition=${key}`;
+            let receipt2 = batched ? prepared?.article_renditions?.find((v) => v.key === key && v.role === role && v.format === r.format) : await request(path);
+            if (batched && !measured(receipt2, state.fileId)) throw Error("Photo batch is missing a required measured receipt; resume the same uploaded file");
+            if (!measured(receipt2, state.fileId)) {
+              const q = new URLSearchParams({ width: String(r.width), fit: r.fit, quality: String(r.quality), format: r.format });
+              if (r.height)
+                q.set("height", String(r.height));
+              const response = await t.fetch(new URL(t.apiUrl.replace(/\/$/, "") + `/v1/photos/public/${state.fileId}/transform?${q}`), { method: "GET", redirect: "manual", signal: deadline });
+              const ok = response.ok && response.headers.get("content-type")?.startsWith("image/") || [302, 303, 307, 308].includes(response.status);
+              await response.body?.cancel();
+              if (!ok)
+                throw Error("Photo could not prepare a required rendition");
+              while (!measured(receipt2, state.fileId)) {
+                receipt2 = await request(path);
+                if (!measured(receipt2, state.fileId))
+                  await sleep();
+              }
+            }
+            return receipt2;
+          })();
+          preparations.set(key, preparation);
+        }
+        const receipt = await preparation;
+        outputs.push({ role, file_id: state.fileId, url: receipt.url, width: receipt.width, height: receipt.height, format: r.format });
+      }
+    }));
+    const leads = outputs.filter((o) => o.role === "lead").sort((a, b) => a.width - b.width || a.format.localeCompare(b.format));
+    const master = [...leads].reverse().find((o) => o.format === "webp") ?? leads.at(-1);
+    const social = outputs.find((o) => o.role === "social" && o.format === "jpeg") ?? outputs.find((o) => o.role === "social");
+    if (!master || !social || leads.length > 20)
+      throw Error("Photo policy has no usable lead or social output");
+    state.payload = {
+      expected_version: state.expectedVersion,
+      cover_image_url: master.url,
+      og_image_url: social.url,
+      cover_image: { file_id: state.fileId, master_url: master.url, width: master.width, height: master.height, aspect_ratio: `${master.width}:${master.height}`, alt: input.alt, caption: input.caption, attribution: input.credit, ai_generated: input.aiGenerated, label: input.label, focal_point: input.focalPoint ?? { x: 0.5, y: 0.5 }, variants: leads.map(({ url, width, height, format }) => ({ url, width, height, format })) },
+      open_graph_image: { file_id: state.fileId, url: social.url, width: social.width, height: social.height, aspect_ratio: `${social.width}:${social.height}` }
+    };
+    await progress("attach");
+    const result = await request(`/articles/${encodeURIComponent(input.articleId)}/media`, "PUT", state.payload);
+    state.attachedVersion = result.version;
+    await progress("verify");
+    const after = await request(postPath);
+    if (!mediaMatches(after, state.payload) || await hash(stableArticle(after)) !== state.articleHash)
+      throw new ArticlePhotoOperationError("VERIFICATION_CONFLICT", stage, "The current article differs from this operation; inspect it before making another change", state.fileId);
+    await progress("verified");
+    return { article_id: input.articleId, file_id: state.fileId, version: after.version, state: "verified", elapsed_ms: Math.round(performance.now() - started) };
+  } catch (error) {
+    if (error instanceof ArticlePhotoOperationError)
+      throw error;
+    const status = typeof error?.status === "number" ? error.status : void 0;
+    const code = deadline.aborted ? "DEADLINE_EXCEEDED" : status === 409 && stage === "attach" ? "ARTICLE_CHANGED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : "STEP_FAILED";
+    throw new ArticlePhotoOperationError(code, stage, deadline.aborted ? "Operation reached its time limit; resume the same operation and checkpoint. Success was not asserted." : error instanceof Error ? error.message : "Article photo operation failed", state?.fileId, status);
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -19,7 +306,7 @@ var PublicationArticleClient = class {
   }
   config;
   base;
-  async request(path, method = "GET", body, extra) {
+  async request(path, method = "GET", body, extra, signal) {
     const headers = new Headers(extra);
     headers.set("accept", "application/json");
     if (this.config.apiKey) headers.set("x-api-key", this.config.apiKey);
@@ -37,7 +324,7 @@ var PublicationArticleClient = class {
       method,
       headers,
       body: body === void 0 ? void 0 : form ? body : JSON.stringify(body),
-      signal: AbortSignal.timeout(form ? 9e4 : 3e4),
+      signal: signal ?? AbortSignal.timeout(form ? 9e4 : 3e4),
       cache: "no-store",
       redirect: "error"
     });
@@ -70,11 +357,18 @@ var PublicationArticleClient = class {
       `/articles/${encodeURIComponent(articleId)}/collaboration`
     );
   }
-  processing(articleId) {
+  processing(articleId, signal) {
     return this.request(
-      `/articles/${encodeURIComponent(articleId)}/processing`
+      `/articles/${encodeURIComponent(articleId)}/processing`,
+      void 0,
+      void 0,
+      void 0,
+      signal
     );
   }
+  uploadAndReplacePublishedCover(input) {
+    return runArticlePhoto({ publicationId: this.config.publicationId, apiUrl: this.config.apiUrl, fetch: this.config.fetch ?? fetch, request: this.request.bind(this) }, input);
+  }
   /** Replace a legacy publication cover using ready, measured public Photo renditions.
    * This never enrolls a story, publishes text, creates narration or retries a conflict.
    * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -260,7 +554,7 @@ var PublicationArticleClient = class {
       const selected = [];
       for (const asset of input.assets ?? []) {
         let current = await this.get(created.article_id);
-        const digest = Array.from(
+        const digest2 = Array.from(
           new Uint8Array(
             await crypto.subtle.digest(
               "SHA-256",
@@ -269,7 +563,7 @@ var PublicationArticleClient = class {
           )
         ).map((v) => v.toString(16).padStart(2, "0")).join("");
         const existing = current.contributions.find(
-          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest && Object.entries(asset.metadata).every(
+          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest2 && Object.entries(asset.metadata).every(
             ([k, v]) => c.payload[k] === v
           )
         );
@@ -350,7 +644,7 @@ var PublicationArticleClient = class {
   }
 };
 function sameDocument(a, b) {
-  const canonical = (d) => [
+  const canonical2 = (d) => [
     d.title,
     d.subtitle || "",
     d.content_markdown,
@@ -368,7 +662,7 @@ function sameDocument(a, b) {
       m.position
     ])
   ];
-  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+  return JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
 }
 
-export { ArticleWorkflowError, PublicationArticleClient };
+export { ArticlePhotoOperationError, ArticleWorkflowError, PublicationArticleClient, articlePhotoHtmlMatches };

package/dist/index.d.cts

@@ -18,7 +18,7 @@ export { C as ContentBlock, S as StructuredDocument, a as StructuredMedia, f as
 import { M as Measurement } from './sponsorships-CtnBe3S8.cjs';
 export { a as Campaign, b as CampaignStatus, c as CampaignTarget, C as Creative, d as Placement, e as PlacementType, P as PublicAcknowledgment, S as SPONSORSHIP_OFFERINGS, f as SPONSORSHIP_POLICY, g as SponsorParty, p as placementAvailable, s as safeSponsorUrl } from './sponsorships-CtnBe3S8.cjs';
 export { R as READER_SSO_EVENTS, a as READER_SSO_PROPERTY_KEYS, b as ReaderSsoEventDefinition, c as ReaderSsoEventName } from './reader-sso-events-DBw8pGSM.cjs';
-export { A as ArticleFormat, a as ArticleLayout, b as ArticlePresentation, c as articleFormatLabel, d as articleHeroRatio, e as articlePresentation } from './article-presentation-BrNCcF-5.cjs';
+export { A as ArticleFormat, b as ArticleLayout, a as ArticlePresentation, c as articleFormatLabel, d as articleHeroRatio, e as articlePresentation } from './article-presentation-0d1FiDgA.cjs';
 import './pets.cjs';
 
 /** Walnut Creek Times broadsheet colors. A paper overrides only what it changes. */

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { C as ContentBlock, S as StructuredDocument, a as StructuredMedia, f as
 import { M as Measurement } from './sponsorships-CtnBe3S8.js';
 export { a as Campaign, b as CampaignStatus, c as CampaignTarget, C as Creative, d as Placement, e as PlacementType, P as PublicAcknowledgment, S as SPONSORSHIP_OFFERINGS, f as SPONSORSHIP_POLICY, g as SponsorParty, p as placementAvailable, s as safeSponsorUrl } from './sponsorships-CtnBe3S8.js';
 export { R as READER_SSO_EVENTS, a as READER_SSO_PROPERTY_KEYS, b as ReaderSsoEventDefinition, c as ReaderSsoEventName } from './reader-sso-events-DBw8pGSM.js';
-export { A as ArticleFormat, a as ArticleLayout, b as ArticlePresentation, c as articleFormatLabel, d as articleHeroRatio, e as articlePresentation } from './article-presentation-BrNCcF-5.js';
+export { A as ArticleFormat, b as ArticleLayout, a as ArticlePresentation, c as articleFormatLabel, d as articleHeroRatio, e as articlePresentation } from './article-presentation-0d1FiDgA.js';
 import './pets.js';
 
 /** Walnut Creek Times broadsheet colors. A paper overrides only what it changes. */

package/dist/story-review.d.cts

@@ -1,4 +1,4 @@
-import { A as ArticleFormat, b as ArticlePresentation } from './article-presentation-BrNCcF-5.cjs';
+import { A as ArticleFormat, a as ArticlePresentation } from './article-presentation-0d1FiDgA.cjs';
 import React__default from 'react';
 import { C as ContentBlock } from './article-blocks-DsabIDmH.cjs';
 

package/dist/story-review.d.ts

@@ -1,4 +1,4 @@
-import { A as ArticleFormat, b as ArticlePresentation } from './article-presentation-BrNCcF-5.js';
+import { A as ArticleFormat, a as ArticlePresentation } from './article-presentation-0d1FiDgA.js';
 import React__default from 'react';
 import { C as ContentBlock } from './article-blocks-DsabIDmH.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/news-publication",
-  "version": "0.0.79",
+  "version": "0.0.80",
   "description": "Shared server framework for ScaleMule local news publications. Walnut Creek Times is the broadsheet default; each paper supplies its own identity and feature flags.",
   "type": "module",
   "bin": {