@gmickel/gno 1.32.0 → 1.33.0

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.32.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.33.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -773,7 +773,7 @@ GNO is local-first, but sometimes you want a URL to send someone. [**gno.sh**](h
 
 ![gno.sh publish reader](./assets/screenshots/publish-reader.jpg)
 
-The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Private and `publish: false` notes stay on your machine. Exported artifacts omit local collection paths and source URIs.
+The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Private and `publish: false` notes stay on your machine. Exported artifacts omit local collection paths and source URIs. Local PNG/JPEG/GIF/WebP/AVIF images (Markdown and Obsidian embeds) are bundled into the artifact with SHA-256 dedup, `gno-asset:` sentinels, and an exact 100 MiB serialized ceiling; external HTTPS images stay as URLs. Encrypted shares keep image bytes inside ciphertext only. Invite-only note text publishes today, but invite-only image delivery on gno.sh is not supported yet.
 
 ```bash
 # Export a single note
@@ -817,6 +817,15 @@ agent capabilities or manifests. Encrypted exports remain ciphertext-only.
 Reader metadata drops embedded local path or GNO/file URI tokens; canonical
 and image fields accept only uncredentialed public HTTP(S) targets.
 
+Resolved local PNG, JPEG, GIF, WebP, and AVIF references are bundled,
+content-addressed, and deduplicated; external public HTTPS images remain
+external. The exact serialized artifact is capped at 100 MiB. Public images
+use immutable snapshot/generation URLs, secret-link images are authorized on
+every request, and encrypted image bytes exist only inside ciphertext before
+the browser creates scoped Blob URLs. Invite-only bundled-image delivery is
+currently fail-closed; use an asset-free invite, secret link, or encrypted
+share when local images are required.
+
 Republishing a public, secret-link, or invite-only artifact updates the same URL. Encrypted shares should be replaced from a fresh local export so the server never needs your plaintext.
 
 Encrypted source-backed publish on `gno.sh` is intentionally disabled. For encrypted shares, use:

package/assets/skill/SKILL.md

@@ -92,6 +92,17 @@ Recipe rules:
 | **Skill**    | `skill install/uninstall/show/paths`                                                                       | Install skill for AI agents                                              |
 | **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`                                                | Maintenance and diagnostics                                              |
 
+### Publishing with local images
+
+`gno publish export` bundles resolved local PNG, JPEG, GIF, WebP, and AVIF
+references, deduplicates identical bytes, preserves public HTTPS images, and
+enforces the 100 MiB exact serialized artifact limit. Review `assetSummary`
+in `--json` output for unresolved or unsupported references. Public and
+secret-link readers serve authorized hosted URLs; encrypted exports keep image
+bytes inside ciphertext and create scoped Blob URLs only after browser
+decryption. Hosted invite-only bundled-image delivery is currently
+fail-closed, so use an asset-free invite, secret link, or encrypted share.
+
 ## Search Modes
 
 | Command                | Speed   | Best For                            |

package/assets/skill/cli-reference.md

@@ -887,11 +887,19 @@ export pipeline runs a sanitizer over each note's markdown. It:
   `_internal/` convention is treated as never-publish)
 - converts `[[Target|Alias]]` to the alias text, and `[[Target]]` to the
   tail segment of the target
-- drops `![[image.png]]` embeds (attachments are not bundled yet) with a
-  warning so the author can migrate to `![alt](url)` or wait for bundling
+- resolves local `![[image.png]]` / Markdown image refs for PNG/JPEG/GIF/WebP/
+  AVIF (AVIF must be AV1-decodable at producer ingress) into content-addressed
+  `gno-asset:<sha256>` sentinels (deduped; exact 100 MiB serialized ceiling;
+  ciphertext field bounds align to that envelope); preserves external HTTPS
+  images; skips fenced code (backtick and tilde); drops unsupported/missing/
+  unsafe refs with diagnostics
 - refuses to export a note whose frontmatter contains `publish: false`
   (single-note export errors; collection export silently skips)
 
+Successful exports include `assetSummary` in `--json`. Encrypted visibility
+keeps raster bytes inside ciphertext only. Hosted invite-only image delivery
+is currently fail-closed on gno.sh.
+
 Every sanitizer decision surfaces in the CLI output as a "Preprocessor
 notes" section, on the `--json` response under `warnings`, and on
 `--preview` as a structured report — so nothing is silently lost.

package/browser-extension/artifacts/gno-browser-clipper-v1.33.0.zip.sha256

@@ -0,0 +1 @@
+c398c09680951afa0b5d436f3b92cf3dfb6e49427b9df83830ce899d3b03d7e4  gno-browser-clipper-v1.33.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.32.0"
+  "version": "1.33.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -178,6 +178,9 @@
     "jsonc-parser": "3.3.1",
     "lucide-react": "1.28.0",
     "markitdown-ts": "0.0.10",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-gfm": "3.1.0",
+    "micromark-extension-gfm": "3.0.0",
     "minimatch": "10.2.6",
     "nanoid": "6.0.0",
     "node-llama-cpp": "3.19.1",
@@ -190,6 +193,7 @@
     "react-markdown": "10.1.0",
     "rehype-sanitize": "6.0.0",
     "remark-gfm": "4.0.1",
+    "sharp": "0.35.3",
     "shiki": "4.3.1",
     "sqlite-vec": "0.1.9",
     "streamdown": "2.5.0",

package/spec/cli.md

@@ -1949,6 +1949,19 @@ tokens MUST be filtered. Canonical and image metadata MUST contain
 uncredentialed public HTTP(S) targets; local hostnames and literal loopback,
 private, or link-local addresses MUST be filtered.
 
+When local raster attachments are bundled, the V1 artifact MAY include
+`assets[]` and `requiredCapabilities: ["bundled-raster-assets@1"]`. Export
+success payloads (CLI `--json` and `POST /api/publish/export`) MUST include a
+deterministic `assetSummary` with asset/ref counts, raw/encoded/final UTF-8
+upload bytes, dedup savings, external image count, and unresolved/unsupported
+diagnostics. Exact final serialized upload bytes MUST be enforced against the
+100 MiB ceiling before returning. Encrypted V2 ciphertext string bounds MUST
+align to that same 100 MiB final-envelope budget and MUST NOT replace exact
+final serialized measurement as the authoritative upload gate. Producer
+ingress MUST require AV1-decodable AVIF payloads (structural BMFF alone is
+insufficient). Asset-free exports omit `assets` /
+`requiredCapabilities` and report zero asset counts.
+
 Secret-link and invite-only V1 spaces MUST NOT contain a manifest or agent
 capability field. Encrypted V2 spaces MUST contain only ciphertext parameters,
 the opaque secret token, route slug, source type, and encrypted visibility; no
@@ -1956,7 +1969,9 @@ plaintext manifest or evidence may appear outside the ciphertext. V2 builders
 MUST emit a closed projection, validate payload strings as non-empty bounded
 base64, require a positive safe-integer KDF iteration count, and bound the
 non-blank opaque token. Caller-supplied extension fields MUST NOT enter the
-artifact.
+artifact. Encrypted export MUST place bundled assets only inside the encrypted
+client payload. The outer V2 envelope MUST contain neither plaintext note
+content, asset descriptors, source references, nor raster bytes.
 
 ---
 

package/spec/output-schemas/publish-artifact.schema.json

@@ -16,6 +16,10 @@
         "egressLineage": { "$ref": "#/definitions/egressLineage" },
         "source": { "$ref": "#/definitions/slug" },
         "exportedAt": { "type": "string", "format": "date-time" },
+        "requiredCapabilities": {
+          "$ref": "#/definitions/requiredCapabilities"
+        },
+        "assets": { "$ref": "#/definitions/assets" },
         "spaces": {
           "type": "array",
           "minItems": 1,
@@ -37,6 +41,9 @@
         "egressLineage": { "$ref": "#/definitions/egressLineage" },
         "source": { "$ref": "#/definitions/slug" },
         "exportedAt": { "type": "string", "format": "date-time" },
+        "requiredCapabilities": {
+          "$ref": "#/definitions/requiredCapabilities"
+        },
         "spaces": {
           "type": "array",
           "minItems": 1,
@@ -44,6 +51,74 @@
         }
       }
     },
+    "requiredCapabilities": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      }
+    },
+    "assets": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/artifactAsset" }
+    },
+    "artifactAsset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "mediaType",
+        "byteLength",
+        "sha256",
+        "width",
+        "height",
+        "encoding",
+        "data",
+        "references"
+      ],
+      "properties": {
+        "id": { "$ref": "#/definitions/hash" },
+        "mediaType": {
+          "enum": [
+            "image/png",
+            "image/jpeg",
+            "image/gif",
+            "image/webp",
+            "image/avif"
+          ]
+        },
+        "byteLength": { "type": "integer", "minimum": 1, "maximum": 104857600 },
+        "sha256": { "$ref": "#/definitions/hash" },
+        "width": { "type": "integer", "minimum": 1, "maximum": 16384 },
+        "height": { "type": "integer", "minimum": 1, "maximum": 16384 },
+        "encoding": { "const": "base64" },
+        "data": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 139810134,
+          "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
+        },
+        "references": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["noteSlug", "sourceRef"],
+            "properties": {
+              "noteSlug": { "$ref": "#/definitions/slug" },
+              "sourceRef": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              }
+            }
+          }
+        }
+      }
+    },
     "slug": {
       "type": "string",
       "pattern": "^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$",
@@ -280,7 +355,7 @@
             "ciphertext": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 67108864,
+              "maxLength": 104857600,
               "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
             },
             "iterations": {

package/src/cli/commands/publish.ts

@@ -4,7 +4,8 @@
  * @module src/cli/commands/publish
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+// node:fs/promises — directory creation has no Bun-native equivalent.
+import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { join } from "node:path";
 
@@ -12,10 +13,15 @@ import type {
   PublishArtifact,
   PublishVisibility,
 } from "../../publish/artifact";
+import type { PublishAssetEgressSummary } from "../../publish/attachment-resolver";
 import type { SanitizeWarning } from "../../publish/obsidian-sanitize";
 
 import { resolveDownloadsDir } from "../../core/user-dirs";
-import { derivePublishArtifactFilename, slugify } from "../../publish/artifact";
+import {
+  derivePublishArtifactFilename,
+  serializePublishArtifact,
+  slugify,
+} from "../../publish/artifact";
 import { exportPublishArtifact } from "../../publish/export-service";
 import { formatSanitizeWarnings } from "../../publish/obsidian-sanitize";
 import { initStore } from "./shared";
@@ -37,6 +43,7 @@ export type PublishExportResult =
       success: true;
       data: {
         artifact: PublishArtifact;
+        assetSummary: PublishAssetEgressSummary;
         outPath: string;
         preview?: string;
         uploadUrl: string;
@@ -64,6 +71,15 @@ export async function buildDefaultPublishExportPath(
   );
 }
 
+/** Write exactly the canonical byte sequence used by upload-size accounting. */
+export async function writePublishArtifactFile(
+  outPath: string,
+  artifact: PublishArtifact
+): Promise<void> {
+  await mkdir(dirname(outPath), { recursive: true });
+  await Bun.write(outPath, serializePublishArtifact(artifact));
+}
+
 export async function publishExport(
   target: string,
   options: PublishExportOptions
@@ -79,7 +95,7 @@ export async function publishExport(
   const { collections, store } = initResult;
 
   try {
-    const { artifact, warnings } = await exportPublishArtifact({
+    const { artifact, assetSummary, warnings } = await exportPublishArtifact({
       collections,
       options: {
         routeSlug: options.slug,
@@ -104,6 +120,7 @@ export async function publishExport(
         success: true,
         data: {
           artifact,
+          assetSummary,
           outPath: "",
           preview,
           uploadUrl: "https://gno.sh/studio",
@@ -116,13 +133,13 @@ export async function publishExport(
     const outPath =
       options.out?.trim() || (await buildDefaultPublishExportPath(artifact));
 
-    await mkdir(dirname(outPath), { recursive: true });
-    await writeFile(outPath, JSON.stringify(artifact, null, 2));
+    await writePublishArtifactFile(outPath, artifact);
 
     return {
       success: true,
       data: {
         artifact,
+        assetSummary,
         outPath,
         uploadUrl: "https://gno.sh/studio",
         warnings,
@@ -159,19 +176,37 @@ export function formatPublishExport(
     return JSON.stringify(result.data, null, 2);
   }
 
-  const { artifact, outPath, preview, uploadUrl, warningsDisplay } =
-    result.data;
+  const {
+    artifact,
+    assetSummary,
+    outPath,
+    preview,
+    uploadUrl,
+    warningsDisplay,
+  } = result.data;
   const space = artifact.spaces[0];
   const warningsSection =
     warningsDisplay.length > 0
       ? ["", "Preprocessor notes:", ...warningsDisplay]
       : [];
+  const assetSection = [
+    "",
+    "Asset summary:",
+    `  assets=${assetSummary.assetCount} refs=${assetSummary.referenceCount} external=${assetSummary.externalCount}`,
+    `  rawBytes=${assetSummary.rawBytes} encodedBytes=${assetSummary.encodedBytes} finalBytes=${assetSummary.finalUploadBytes}`,
+    `  dedupSavedBytes=${assetSummary.dedupSavedBytes} unresolved=${assetSummary.diagnostics.length}`,
+    ...assetSummary.diagnostics.map(
+      (diagnostic) =>
+        `  [${diagnostic.code}] ${diagnostic.noteSlug}: ${diagnostic.sourceRef} — ${diagnostic.message}`
+    ),
+  ];
 
   if (preview !== undefined) {
     return [
       `Preview (no file written) — ${space?.sourceType ?? "artifact"}`,
       `Route slug: ${space?.routeSlug ?? slugify(artifact.source)}`,
       `Visibility: ${space?.visibility ?? "public"}`,
+      ...assetSection,
       ...warningsSection,
       "",
       "─── sanitized markdown ───",
@@ -185,6 +220,7 @@ export function formatPublishExport(
     `Visibility: ${space?.visibility ?? "public"}`,
     `Filename: ${derivePublishArtifactFilename(artifact)}`,
     `Next: open ${uploadUrl} and drop ${outPath} into the upload zone.`,
+    ...assetSection,
     ...warningsSection,
   ].join("\n");
 }

package/src/ingestion/strip.ts

@@ -3,7 +3,7 @@
  *
  * Identifies regions to exclude from link/tag extraction:
  * - YAML frontmatter
- * - Fenced code blocks
+ * - Fenced code blocks (CommonMark backtick and tilde fences)
  * - Inline code
  * - HTML comments
  *
@@ -39,15 +39,153 @@ export interface ExcludedRange {
 /** Frontmatter at start of file (YAML between --- delimiters) */
 const FRONTMATTER_REGEX = /^---\r?\n[\s\S]*?(?:\r?\n)?---(?:\r?\n|$)/;
 
-/** Fenced code blocks (``` with optional language) */
-const FENCED_CODE_REGEX = /^```[^\n]*\n[\s\S]*?^```/gm;
+/** CommonMark fence opener: 0–3 spaces, then 3+ backticks or tildes + info. */
+const FENCE_OPEN_REGEX = /^ {0,3}(`{3,}|~{3,})(.*)$/u;
 
-/** Inline code (backticks, non-greedy) */
-const INLINE_CODE_REGEX = /`[^`\n]+`/g;
+/** CommonMark fence closer: matching character, length ≥ opener, trailing space/tabs only. */
+const FENCE_CLOSE_REGEX = /^ {0,3}(`{3,}|~{3,})[\t ]*$/u;
 
 /** HTML comments */
 const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
 
+interface OpenFence {
+  marker: "`" | "~";
+  length: number;
+  start: number;
+}
+
+/**
+ * Collect CommonMark fenced code ranges (backtick and tilde). A closer must
+ * use the same character and be at least as long as the opener; when omitted,
+ * CommonMark extends the fenced block through end of input.
+ */
+const collectFencedCodeRanges = (markdown: string): ExcludedRange[] => {
+  const ranges: ExcludedRange[] = [];
+  let offset = 0;
+  let open: OpenFence | null = null;
+
+  while (offset <= markdown.length) {
+    const nextNl = markdown.indexOf("\n", offset);
+    const lineEnd = nextNl === -1 ? markdown.length : nextNl;
+    const rawLine = markdown.slice(offset, lineEnd);
+    const logical = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+
+    if (open) {
+      const closeRun = FENCE_CLOSE_REGEX.exec(logical)?.[1];
+      if (
+        closeRun &&
+        closeRun[0] === open.marker &&
+        closeRun.length >= open.length
+      ) {
+        const end = nextNl === -1 ? markdown.length : nextNl + 1;
+        ranges.push({ start: open.start, end, kind: "fenced_code" });
+        open = null;
+      }
+    } else {
+      const openMatch = FENCE_OPEN_REGEX.exec(logical);
+      const run = openMatch?.[1];
+      const suffix = openMatch?.[2] ?? "";
+      // Backtick info strings cannot contain backticks (CommonMark).
+      if (run && !(run[0] === "`" && suffix.includes("`"))) {
+        open = {
+          marker: run[0] as OpenFence["marker"],
+          length: run.length,
+          start: offset,
+        };
+      }
+    }
+
+    if (nextNl === -1) break;
+    offset = nextNl + 1;
+  }
+
+  if (open) {
+    ranges.push({
+      start: open.start,
+      end: markdown.length,
+      kind: "fenced_code",
+    });
+  }
+
+  return ranges;
+};
+
+interface BacktickRun {
+  end: number;
+  length: number;
+  start: number;
+}
+
+/** CommonMark code spans close only on a backtick run of equal length. */
+const collectInlineCodeRanges = (
+  markdown: string,
+  excludedRanges: ExcludedRange[]
+): ExcludedRange[] => {
+  const runs: BacktickRun[] = [];
+  let cursor = 0;
+  let excludedIndex = 0;
+  while (cursor < markdown.length) {
+    while (
+      excludedRanges[excludedIndex] &&
+      excludedRanges[excludedIndex]!.end <= cursor
+    ) {
+      excludedIndex += 1;
+    }
+    const excluded = excludedRanges[excludedIndex];
+    if (excluded && cursor >= excluded.start && cursor < excluded.end) {
+      cursor = excluded.end;
+      continue;
+    }
+    if (markdown[cursor] !== "`") {
+      cursor += 1;
+      continue;
+    }
+    const start = cursor;
+    while (markdown[cursor] === "`") cursor += 1;
+    let backslashes = 0;
+    for (let i = start - 1; i >= 0 && markdown[i] === "\\"; i -= 1) {
+      backslashes += 1;
+    }
+    if (backslashes % 2 === 0) {
+      runs.push({ start, end: cursor, length: cursor - start });
+    }
+  }
+
+  const nextMatchingRun = Array.from<number | undefined>({
+    length: runs.length,
+  });
+  const latestByLength = new Map<number, number>();
+  for (let index = runs.length - 1; index >= 0; index -= 1) {
+    const run = runs[index];
+    if (!run) continue;
+    nextMatchingRun[index] = latestByLength.get(run.length);
+    latestByLength.set(run.length, index);
+  }
+
+  const ranges: ExcludedRange[] = [];
+  let index = 0;
+  while (index < runs.length) {
+    const closeIndex = nextMatchingRun[index];
+    const opener = runs[index];
+    if (closeIndex === undefined || !opener) {
+      index += 1;
+      continue;
+    }
+    const closer = runs[closeIndex];
+    if (!closer) {
+      index += 1;
+      continue;
+    }
+    ranges.push({
+      start: opener.start,
+      end: closer.end,
+      kind: "inline_code",
+    });
+    index = closeIndex + 1;
+  }
+  return ranges;
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main Functions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -70,29 +208,12 @@ export function getExcludedRanges(markdown: string): ExcludedRange[] {
     });
   }
 
-  // 2. Fenced code blocks
-  FENCED_CODE_REGEX.lastIndex = 0;
-  let match: RegExpExecArray | null;
-  while ((match = FENCED_CODE_REGEX.exec(markdown)) !== null) {
-    ranges.push({
-      start: match.index,
-      end: match.index + match[0].length,
-      kind: "fenced_code",
-    });
-  }
-
-  // 3. Inline code
-  INLINE_CODE_REGEX.lastIndex = 0;
-  while ((match = INLINE_CODE_REGEX.exec(markdown)) !== null) {
-    ranges.push({
-      start: match.index,
-      end: match.index + match[0].length,
-      kind: "inline_code",
-    });
-  }
+  // 2. Fenced code blocks (backtick + tilde, CommonMark matching rules)
+  ranges.push(...collectFencedCodeRanges(markdown));
 
-  // 4. HTML comments
+  // 3. HTML comments
   HTML_COMMENT_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
   while ((match = HTML_COMMENT_REGEX.exec(markdown)) !== null) {
     ranges.push({
       start: match.index,
@@ -101,6 +222,11 @@ export function getExcludedRanges(markdown: string): ExcludedRange[] {
     });
   }
 
+  // 4. Inline code. Pair delimiters only in visible prose so unmatched
+  // backticks inside already-excluded blocks cannot consume later content.
+  ranges.sort((a, b) => a.start - b.start);
+  ranges.push(...collectInlineCodeRanges(markdown, ranges));
+
   // Sort by start position for efficient lookup
   ranges.sort((a, b) => a.start - b.start);
 

package/src/publish/artifact-asset-codec.ts

@@ -0,0 +1,75 @@
+/**
+ * Synchronous SHA-256 + base64 helpers for publish assets.
+ * Bun.CryptoHasher for digests; browser-safe atob for base64 decode parity with gno.sh.
+ *
+ * @module src/publish/artifact-asset-codec
+ */
+
+/** Synchronous SHA-256 hex digest over raw bytes (Bun-native). */
+export const sha256BytesHex = (bytes: Uint8Array): string => {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(bytes);
+  return hasher.digest("hex");
+};
+
+const BASE64_PATTERN =
+  /^(?:[a-zA-Z0-9+/]{4})*(?:[a-zA-Z0-9+/]{2}==|[a-zA-Z0-9+/]{3}=)?$/u;
+
+/**
+ * Encode raw bytes to standard base64 without Node Buffer.
+ * Prefers Bun/Web Uint8Array.toBase64(); falls back to btoa for parity with decode.
+ */
+export const encodeBytesToBase64 = (bytes: Uint8Array): string => {
+  if (typeof bytes.toBase64 === "function") {
+    return bytes.toBase64();
+  }
+  const CHUNK = 0x8000;
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += CHUNK) {
+    const slice = bytes.subarray(offset, offset + CHUNK);
+    binary += String.fromCharCode(...slice);
+  }
+  return btoa(binary);
+};
+
+/** Decode standard base64 without Buffer (uses atob). */
+export const decodeBase64ToBytes = (
+  data: string
+): { ok: true; bytes: Uint8Array } | { ok: false } => {
+  if (!BASE64_PATTERN.test(data) || data.length === 0) return { ok: false };
+  try {
+    const binary = atob(data);
+    if (binary.length === 0 && data.replace(/=+$/u, "").length > 0) {
+      return { ok: false };
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return { ok: true, bytes };
+  } catch {
+    return { ok: false };
+  }
+};
+
+const UTF8 = new TextEncoder();
+
+export const measureSerializedUploadBytes = (serializedBody: string): number =>
+  UTF8.encode(serializedBody).byteLength;
+
+/**
+ * Canonical on-disk/upload serialization for publish artifacts.
+ *
+ * Byte-budget enforcement and every artifact writer must use this exact
+ * representation so `finalUploadBytes` describes the bytes handed to gno.sh.
+ */
+export const serializePublishArtifact = (artifact: unknown): string => {
+  const serialized = JSON.stringify(artifact, null, 2);
+  if (serialized === undefined) {
+    throw new TypeError("Publish artifact is not JSON-serializable");
+  }
+  return serialized;
+};
+
+export const measureArtifactUploadBytes = (artifact: unknown): number =>
+  measureSerializedUploadBytes(serializePublishArtifact(artifact));