@scalemule/news-publication 0.0.79 → 0.0.81

package/dist/article-workflow-client.cjs

@@ -1,5 +1,652 @@
 '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-edit-verification.ts
+var decode = (value) => value.replace(/&(?:amp|lt|gt|quot|apos|#39|#\d+|#x[\da-f]+);/giu, (s) => {
+  const named = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'"
+  };
+  if (named[s.toLowerCase()]) return named[s.toLowerCase()];
+  const hex = s.toLowerCase().startsWith("&#x");
+  const n = parseInt(s.slice(hex ? 3 : 2, -1), hex ? 16 : 10);
+  return Number.isFinite(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : s;
+});
+var text = (html) => decode(html.replace(/<[^>]*>/gu, " ")).replace(/\s+/gu, " ").trim();
+var plain = (value) => value.replace(/\s+/gu, " ").trim();
+function articleEditHtmlMatches(html, expected) {
+  const visible = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/giu, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/giu, " ");
+  const headline = [...visible.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/giu)].some(
+    (m) => text(m[1]) === plain(expected.title)
+  );
+  if (!headline) return false;
+  const paragraphs = [
+    ...expected.content_html.matchAll(
+      /<(p|li|h[2-6]|blockquote)\b[^>]*>([\s\S]*?)<\/\1>/giu
+    )
+  ].map((m) => text(m[2])).filter(Boolean);
+  const all = text(visible);
+  if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
+    return false;
+  const titles = [
+    ...visible.matchAll(
+      /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
+    )
+  ].flatMap(
+    (m) => [...m[1].matchAll(/<h2\b[^>]*>([\s\S]*?)<\/h2>/giu)].map((m2) => text(m2[1]))
+  );
+  return JSON.stringify(titles.sort()) === JSON.stringify(expected.card_titles.map(plain).sort());
+}
+
+// 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-edit-operation.ts
+var ArticleEditOperationError = class extends Error {
+  constructor(code, stage, message, status, revisionId) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.status = status;
+    this.revisionId = revisionId;
+    this.name = "ArticleEditOperationError";
+  }
+  code;
+  stage;
+  status;
+  revisionId;
+};
+var canonical2 = (v) => Array.isArray(v) ? v.map(canonical2) : v && typeof v === "object" ? Object.fromEntries(
+  Object.keys(v).sort().map((k) => [k, canonical2(v[k])])
+) : v;
+var equal = (a, b) => JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+var digest2 = async (v) => [
+  ...new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(JSON.stringify(canonical2(v)))
+    )
+  )
+].map((v2) => v2.toString(16).padStart(2, "0")).join("");
+var patchKeys = /* @__PURE__ */ new Set([
+  "title",
+  "subtitle",
+  "content_markdown",
+  "excerpt",
+  "section",
+  "community",
+  "format",
+  "layout",
+  "cards",
+  "citations"
+]);
+function validate(input) {
+  if (!input.operationKey || !/^[\w.:-]{1,128}$/u.test(input.operationKey) || !input.articleId || !input.patch || typeof input.patch !== "object" || Array.isArray(input.patch) || !Object.keys(input.patch).length)
+    throw Error(
+      "Supply an article, stable operation key and nonempty editorial patch"
+    );
+  for (const [key, value] of Object.entries(input.patch)) {
+    if (!patchKeys.has(key)) throw Error("Unsupported edit field: " + key);
+    if (["cards", "citations"].includes(key)) {
+      if (!Array.isArray(value)) throw Error(key + " must be an array");
+    } else if (key === "layout") {
+      if (!value || typeof value !== "object" || typeof value.id !== "string" || !Number.isInteger(value.version))
+        throw Error("Select an existing versioned layout");
+    } else if (typeof value !== "string")
+      throw Error(key + " must be a string");
+  }
+  if (input.expectedGeneration !== void 0 && (!Number.isSafeInteger(input.expectedGeneration) || input.expectedGeneration < 1))
+    throw Error("Expected generation must be positive");
+  if (input.enableReviewPolicy && ![
+    "NONE",
+    "FACT_CHECK",
+    "CONTRIBUTOR_REVIEW",
+    "SUBJECT_APPROVAL_REQUIRED",
+    "SUBJECT_APPROVAL_PLUS_EDITOR"
+  ].includes(input.enableReviewPolicy))
+    throw Error("Select an explicit supported review policy");
+  if (new TextEncoder().encode(JSON.stringify(input.patch)).length > 128 * 1024)
+    throw Error("Editorial patch exceeds 128 KiB");
+}
+async function runArticleEdit(t, input) {
+  validate(input);
+  const started = performance.now();
+  let stage = "preflight";
+  const timeout = input.timeoutMs ?? 1e4;
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 12e4)
+    throw Error("Edit deadline must be between 100 and 120000 milliseconds");
+  const signal = AbortSignal.timeout(timeout);
+  const request = (path, method, body, extra) => t.request(path, method, body, extra, signal);
+  const identity = await digest2([
+    t.publicationId,
+    input.articleId,
+    input.operationKey,
+    input.patch,
+    input.expectedGeneration ?? null,
+    input.enableReviewPolicy ?? null
+  ]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity || input.checkpoint.articleId !== input.articleId))
+    throw new ArticleEditOperationError(
+      "OPERATION_CONFLICT",
+      "validation",
+      "This checkpoint belongs to different input; reuse its original patch and operation key"
+    );
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : { version: 1, identity, articleId: input.articleId, stage };
+  const save = async (next) => {
+    stage = next;
+    state.stage = next;
+    await input.saveCheckpoint(structuredClone(state));
+  };
+  const article = "/articles/" + encodeURIComponent(input.articleId);
+  const currentRevision = (record) => record.revisions?.find((v) => v.id === record.current_revision_id);
+  const identityOf = (post) => ({
+    slug: post.slug,
+    published_at: post.published_at ?? null,
+    canonical_url: post.canonical_url ?? null
+  });
+  const identityMatches = (post) => !state.sourceIdentity || state.sourceIdentity.slug === post.slug && (state.sourceIdentity.published_at === null || state.sourceIdentity.published_at === (post.published_at ?? null)) && (state.sourceIdentity.canonical_url === null || state.sourceIdentity.canonical_url === (post.canonical_url ?? null));
+  const result = (record, status) => ({
+    article_id: input.articleId,
+    revision_id: state.revisionId ?? record.current_revision_id,
+    generation: record.generation,
+    state: status,
+    editorial_status: record.status,
+    elapsed_ms: Math.round(performance.now() - started)
+  });
+  try {
+    const [options, source, initial] = await Promise.all([
+      request(
+        "/article-workflow/options?article_id=" + encodeURIComponent(input.articleId)
+      ),
+      request(article + "/document"),
+      request(article + "/collaboration").catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return null;
+        throw error;
+      })
+    ]);
+    if (options.workflow_version !== 1 || options.capabilities?.versioned_editorial_fields !== true)
+      throw new ArticleEditOperationError(
+        "CAPABILITY_UNAVAILABLE",
+        stage,
+        "The server must expose versioned_editorial_fields before this edit; no article was changed"
+      );
+    if (!identityMatches(source))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "Article URL, publication date or canonical identity changed; inspect before continuing"
+      );
+    state.sourceIdentity ??= identityOf(source);
+    let record = initial;
+    if (!record) {
+      if (!input.enableReviewPolicy)
+        throw new ArticleEditOperationError(
+          "ENROLLMENT_REQUIRED",
+          stage,
+          "Legacy article: choose an explicit review policy for versioned editorial onboarding; no content was changed"
+        );
+      if (source.status === "scheduled")
+        throw new ArticleEditOperationError(
+          "SCHEDULED_ARTICLE",
+          stage,
+          "Onboarding cancels an old schedule; handle this scheduled article explicitly"
+        );
+      await save("enroll");
+      await request(article + "/collaboration/enable", "POST", {
+        review_policy: input.enableReviewPolicy
+      });
+      record = await request(article + "/collaboration");
+    }
+    if (state.revisionId) {
+      if (record.current_revision_id !== state.revisionId)
+        throw new ArticleEditOperationError(
+          "ARTICLE_CHANGED",
+          stage,
+          "Another revision is current; this operation cannot release or overwrite it",
+          409,
+          state.revisionId
+        );
+      const selected = currentRevision(record);
+      if (!selected || !equal(selected.document, state.document))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "The saved revision differs from this operation",
+          409,
+          state.revisionId
+        );
+    } else {
+      if (!state.document) {
+        if (input.expectedGeneration !== void 0 && record.generation !== input.expectedGeneration)
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "The article generation changed; reload before applying this patch",
+            409
+          );
+        const selected = currentRevision(record);
+        if (!selected?.complete_snapshot && selected?.complete_snapshot !== void 0)
+          throw new ArticleEditOperationError(
+            "INCOMPLETE_REVISION",
+            stage,
+            "Inspect this historical revision before editing"
+          );
+        if (!selected?.document)
+          throw Error("Current immutable article document is missing");
+        const effective = { ...selected.document };
+        for (const key of ["cards", "citations"])
+          if (effective[key] === void 0 && selected.editorial_metadata?.[key] !== void 0)
+            effective[key] = selected.editorial_metadata[key];
+        if (effective.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+          effective.excerpt = source.excerpt;
+        const changed = Object.entries(input.patch).some(
+          ([key, value]) => !equal(effective[key], value)
+        );
+        if (!changed) {
+          state.document = selected.document;
+          state.revisionId = record.current_revision_id;
+          state.savedGeneration = record.generation;
+          state.unchanged = true;
+          await save("verify");
+          if (!input.release) return result(record, "unchanged");
+        } else {
+          const document = { ...selected.document, ...input.patch };
+          if (document.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+            document.excerpt = source.excerpt;
+          state.document = document;
+          state.expectedGeneration = record.generation;
+          await save("save");
+        }
+      }
+      if (!state.revisionId) {
+        const saved = await request(
+          "/article-workflow",
+          "POST",
+          {
+            operation: "save",
+            article_id: input.articleId,
+            expected_generation: state.expectedGeneration,
+            document: state.document,
+            reason: state.sourceIdentity?.published_at ? "POST_PUBLICATION_CORRECTION" : "EDITOR_EDIT"
+          },
+          { "Idempotency-Key": input.operationKey }
+        );
+        state.revisionId = saved.revision_id;
+        state.savedGeneration = saved.generation;
+        await save("verify");
+        record = await request(article + "/collaboration");
+        if (record.current_revision_id !== state.revisionId || !equal(currentRevision(record)?.document, state.document))
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "A different revision is current; no release was attempted",
+            409,
+            state.revisionId
+          );
+      }
+    }
+    if (record.published_revision_id === state.revisionId) {
+      await save("published");
+      return result(record, "already_published");
+    }
+    if (!input.release) {
+      await save("saved");
+      return result(record, state.unchanged ? "unchanged" : "saved_for_review");
+    }
+    await save("release");
+    try {
+      await request(article + "/collaboration", "POST", {
+        action: "RELEASE",
+        expected_generation: record.generation,
+        scheduled_at: null
+      });
+    } catch (error) {
+      const checked = await request(article + "/collaboration");
+      if (checked.published_revision_id === state.revisionId && checked.current_revision_id === state.revisionId) {
+        record = checked;
+      } else throw error;
+    }
+    record = await request(article + "/collaboration");
+    if (record.current_revision_id !== state.revisionId || record.published_revision_id !== state.revisionId)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "This exact revision has not been confirmed published",
+        409,
+        state.revisionId
+      );
+    const after = await request(article + "/document");
+    if (!identityMatches(after))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "The release changed a permanent article identity",
+        409,
+        state.revisionId
+      );
+    for (const key of ["title", "subtitle", "content_markdown", "excerpt"])
+      if (state.document?.[key] !== void 0 && !equal(after[key] ?? "", state.document[key]))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "Public article field differs after release: " + key,
+          409,
+          state.revisionId
+        );
+    const normalizedCards = state.document?.cards;
+    if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "Public card count differs from the saved revision",
+        409,
+        state.revisionId
+      );
+    await save("published");
+    return result(record, "published");
+  } catch (error) {
+    if (error instanceof ArticleEditOperationError) throw error;
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : "Article edit failed";
+    const code = signal.aborted ? "DEADLINE_EXCEEDED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : status === 409 && stage === "release" ? "RELEASE_HELD" : status === 409 ? "ARTICLE_CHANGED" : "STEP_FAILED";
+    throw new ArticleEditOperationError(
+      code,
+      stage,
+      signal.aborted ? "Edit reached its deadline; resume the same patch, operation key and checkpoint. Success was not asserted." : message,
+      status,
+      state.revisionId
+    );
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -21,7 +668,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 +686,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"
     });
@@ -56,6 +703,9 @@ var PublicationArticleClient = class {
       `/article-workflow/options${articleId ? `?article_id=${encodeURIComponent(articleId)}` : ""}`
     );
   }
+  publicArticle(slug, signal) {
+    return this.request("/article-content/" + encodeURIComponent(slug), void 0, void 0, void 0, signal);
+  }
   /** Explicit approver-authorized onboarding for a legacy article; never called by get().
    * Existing schedules are cancelled by the server; public content remains unchanged.
    * Missing immutable media identities must be resolved through newsroom media controls.
@@ -72,11 +722,22 @@ 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);
+  }
+  /** Save one exact revision; release is explicit and never manufactures approval. */
+  editArticle(input) {
+    return runArticleEdit({ publicationId: this.config.publicationId, 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 +923,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 digest3 = Array.from(
           new Uint8Array(
             await crypto.subtle.digest(
               "SHA-256",
@@ -271,7 +932,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 === digest3 && Object.entries(asset.metadata).every(
             ([k, v]) => c.payload[k] === v
           )
         );
@@ -352,10 +1013,14 @@ var PublicationArticleClient = class {
   }
 };
 function sameDocument(a, b) {
-  const canonical = (d) => [
+  const sorted = (v) => Array.isArray(v) ? v.map(sorted) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
+  const canonical3 = (d) => [
     d.title,
     d.subtitle || "",
     d.content_markdown,
+    d.excerpt ?? null,
+    sorted(d.cards ?? null),
+    sorted(d.citations ?? null),
     d.section,
     d.community || "",
     d.format || null,
@@ -370,8 +1035,12 @@ function sameDocument(a, b) {
       m.position
     ])
   ];
-  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+  return JSON.stringify(canonical3(a)) === JSON.stringify(canonical3(b));
 }
 
+exports.ArticleEditOperationError = ArticleEditOperationError;
+exports.ArticlePhotoOperationError = ArticlePhotoOperationError;
 exports.ArticleWorkflowError = ArticleWorkflowError;
 exports.PublicationArticleClient = PublicationArticleClient;
+exports.articleEditHtmlMatches = articleEditHtmlMatches;
+exports.articlePhotoHtmlMatches = articlePhotoHtmlMatches;