docs: document media helpers

src/media/audio-tags.ts

@@ -1,3 +1,4 @@
+// Audio tag helpers parse inline audio directives from message text.
 import { parseInlineDirectives } from "../utils/directive-tags.js";
 
 /**

src/media/audio-transcode.test.ts

@@ -1,3 +1,4 @@
+// Audio transcode tests cover ffmpeg-backed audio conversion behavior.
 import { existsSync, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";

src/media/audio-transcode.ts

@@ -1,3 +1,4 @@
+// Audio transcode helpers run ffmpeg to convert audio for provider requirements.
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { basenameFromAnyPath } from "@openclaw/media-core/file-name";

src/media/audio.test.ts

@@ -1,3 +1,4 @@
+// Audio media tests cover audio type normalization and extension mapping.
 import { describe, expect, it } from "vitest";
 import {
   isVoiceCompatibleAudio,

src/media/audio.ts

@@ -1,3 +1,4 @@
+// Audio media helpers normalize audio mime types, extensions, and load options.
 import { getFileExtension, normalizeMimeType } from "@openclaw/media-core/mime";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 

src/media/channel-inbound-roots.fast-path.test.ts

@@ -1,3 +1,4 @@
+// Channel inbound root fast-path tests cover cached media root resolution.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { MsgContext } from "../auto-reply/templating.js";
 import type { OpenClawConfig } from "../config/types.js";

src/media/channel-inbound-roots.ts

@@ -1,3 +1,4 @@
+// Channel inbound root helpers resolve media roots for channel-delivered files.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { MsgContext } from "../auto-reply/templating.js";
 import type { OpenClawConfig } from "../config/types.js";

src/media/configured-max-bytes.ts

@@ -1,3 +1,4 @@
+// Configured media size helpers resolve maximum byte limits by media kind.
 import { maxBytesForKind, type MediaKind } from "@openclaw/media-core/constants";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 

src/media/document-extractors.runtime.test.ts

@@ -1,3 +1,4 @@
+// Document extractor runtime tests cover lazy document extraction adapters.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const { resolvePluginDocumentExtractorsMock } = vi.hoisted(() => ({

src/media/document-extractors.runtime.ts

@@ -1,3 +1,4 @@
+// Document extractor runtime helpers choose lazy extraction adapters by media type.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {

src/media/fetch.test.ts

@@ -1,3 +1,4 @@
+// Media fetch tests cover remote media download limits and validation.
 import fs from "node:fs/promises";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { MAX_TIMER_TIMEOUT_MS } from "../shared/number-coercion.js";

src/media/fetch.ts

@@ -1,3 +1,4 @@
+// Media fetch helpers download and validate remote media payloads.
 import { MAX_DOCUMENT_BYTES } from "@openclaw/media-core/constants";
 import { parseMediaContentLength } from "@openclaw/media-core/content-length";
 import { basenameFromAnyPath, extnameFromAnyPath } from "@openclaw/media-core/file-name";

src/media/ffmpeg-exec.test.ts

@@ -1,3 +1,4 @@
+// FFmpeg exec tests cover command execution wrappers and error mapping.
 import type { ChildProcess, ExecFileOptions } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";

src/media/ffmpeg-exec.ts

@@ -1,3 +1,4 @@
+// FFmpeg exec helpers run ffmpeg and ffprobe with normalized errors.
 import { execFile, type ExecFileOptions } from "node:child_process";
 import { promisify } from "node:util";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";

src/media/file-context.test.ts

@@ -1,3 +1,4 @@
+// File context tests cover readable context generation for media references.
 import { describe, expect, it } from "vitest";
 import { renderFileContextBlock } from "./file-context.js";
 

src/media/file-context.ts

@@ -1,3 +1,4 @@
+// File context helpers build user-visible context for media file references.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { sanitizeUntrustedFileName } from "../infra/fs-safe-advanced.js";
 

src/media/image-ops.helpers.test.ts

@@ -1,3 +1,4 @@
+// Image operation helper tests cover dimension and format utility behavior.
 import { describe, expect, it } from "vitest";
 import { buildImageResizeSideGrid, IMAGE_REDUCE_QUALITY_STEPS } from "./image-ops.js";
 

src/media/image-ops.rastermill-adapter.test.ts

@@ -1,3 +1,4 @@
+// Raster image adapter tests cover image operation integration with RasterMill.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 describe("image ops Rastermill adapter", () => {

src/media/image-ops.ts

@@ -1,3 +1,4 @@
+// Image operation helpers normalize image transforms and adapter calls.
 import {
   createRastermill,
   isRastermillUnavailableError,

src/media/input-files.fetch-guard.test.ts

@@ -1,3 +1,4 @@
+// Input file fetch guard tests cover network fetch limits for media inputs.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const fetchWithSsrFGuardMock = vi.fn();

src/media/input-files.ts

@@ -1,3 +1,4 @@
+// Input file helpers normalize inline, fetched, and local media inputs.
 import { canonicalizeBase64, estimateBase64DecodedBytes } from "@openclaw/media-core/base64";
 import { parseMediaContentLength } from "@openclaw/media-core/content-length";
 import { detectMime } from "@openclaw/media-core/mime";

src/media/load-options.test.ts

@@ -1,3 +1,4 @@
+// Media load option tests cover normalized media load policy.
 import { describe, expect, it } from "vitest";
 import { buildOutboundMediaLoadOptions, resolveOutboundMediaLocalRoots } from "./load-options.js";
 

src/media/local-media-access.test.ts

@@ -1,3 +1,4 @@
+// Local media access tests cover workspace path authorization.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/media/local-media-access.ts

@@ -1,3 +1,4 @@
+// Local media access helpers validate workspace-local media path access.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { isInboundPathAllowed } from "@openclaw/media-core/inbound-path-policy";

src/media/local-roots.test.ts

@@ -1,3 +1,4 @@
+// Local media root tests cover allowed root normalization and matching.
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterEach, describe, expect, it, vi } from "vitest";

src/media/local-roots.ts

@@ -1,3 +1,4 @@
+// Local media root helpers normalize and match allowed local media roots.
 import path from "node:path";
 import { isPassThroughRemoteMediaSource } from "@openclaw/media-core/media-source-url";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";

src/media/media-reference.test.ts

@@ -1,3 +1,4 @@
+// Media reference tests cover resolving refs to local, remote, and inline media.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

src/media/media-reference.ts

@@ -1,3 +1,4 @@
+// Media reference helpers resolve media refs to file, URL, or inline payloads.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { safeFileURLToPath } from "../infra/local-file-access.js";

src/media/outbound-attachment.test.ts

@@ -1,3 +1,4 @@
+// Outbound attachment tests cover media loading rules for outgoing messages.
 import { describe, expect, it, vi } from "vitest";
 
 const loadWebMedia = vi.hoisted(() => vi.fn());

src/media/outbound-attachment.ts

@@ -1,3 +1,4 @@
+// Outbound attachment helpers prepare media attachments for channel delivery.
 import { buildOutboundMediaLoadOptions, type OutboundMediaAccess } from "./load-options.js";
 import { saveMediaBuffer } from "./store.js";
 import { loadWebMedia } from "./web-media.js";

src/media/parse.test.ts

@@ -1,3 +1,4 @@
+// Media parse tests cover media reference parsing from text and payloads.
 import { describe, expect, it } from "vitest";
 import { splitMediaFromOutput, type SplitMediaFromOutputOptions } from "./parse.js";
 

src/media/parse.ts

@@ -1,3 +1,4 @@
+// Media parse helpers normalize media references from user and channel input.
 import {
   extractEmbeddedIpv4FromIpv6,
   isBlockedSpecialUseIpv4Address,

src/media/pdf-extract.test.ts

@@ -1,3 +1,4 @@
+// PDF extraction tests cover text extraction adapter selection and failures.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const { extractDocumentContentMock } = vi.hoisted(() => ({

src/media/pdf-extract.ts

@@ -1,3 +1,4 @@
+// PDF extraction helpers read PDF text through configured document extraction.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {
   DocumentExtractedImage,

src/media/png-encode.ts

@@ -1,3 +1,4 @@
+// PNG encode helpers build small PNG files without external image dependencies.
 import { deflateSync } from "node:zlib";
 
 const CRC_TABLE = (() => {

src/media/qr-image.test.ts

@@ -1,3 +1,4 @@
+// QR image tests cover QR image generation and file output.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/media/qr-image.ts

@@ -1,3 +1,4 @@
+// QR image helpers generate QR code image files for media delivery.
 import path from "node:path";
 import { tempWorkspace } from "../infra/private-temp-workspace.js";
 import { loadQrCodeRuntime, normalizeQrText } from "./qr-runtime.ts";

src/media/qr-runtime.ts

@@ -1,3 +1,4 @@
+// QR runtime helpers lazily load QR code generation and normalize QR text.
 import type QRCode from "qrcode";
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 

src/media/qr-terminal.render.test.ts

@@ -1,3 +1,4 @@
+// QR terminal render tests cover terminal QR output formatting.
 import QRCode from "qrcode";
 import { describe, expect, it } from "vitest";
 import { renderQrTerminal } from "./qr-terminal.ts";

src/media/qr-terminal.test.ts

@@ -1,3 +1,4 @@
+// QR terminal tests cover text normalization and terminal render calls.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const { create, toString } = vi.hoisted(() => ({

src/media/qr-terminal.ts

@@ -1,3 +1,4 @@
+// QR terminal helpers render QR codes for terminal output.
 import { loadQrCodeRuntime, normalizeQrText } from "./qr-runtime.ts";
 
 type QrTerminalModules = {

src/media/read-capability.test.ts

@@ -1,3 +1,4 @@
+// Media read capability tests cover allowed roots and blocked file access.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import { getDefaultMediaLocalRoots } from "./local-roots.js";

src/media/read-capability.ts

@@ -1,3 +1,4 @@
+// Media read capability helpers gate file reads by configured media access rules.
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";

src/media/sniff-mime-from-base64.test.ts

@@ -1,3 +1,4 @@
+// Base64 mime sniffing tests cover type inference from encoded media payloads.
 import { describe, expect, it } from "vitest";
 import { sniffMimeFromBase64 } from "./sniff-mime-from-base64.js";
 

src/media/sniff-mime-from-base64.ts

@@ -1,3 +1,4 @@
+// Base64 mime sniffing helpers infer media types from encoded payload bytes.
 import { canonicalizeBase64 } from "@openclaw/media-core/base64";
 import { detectMime } from "@openclaw/media-core/mime";
 

src/media/store.outside-workspace.test.ts

@@ -1,3 +1,4 @@
+// Outside-workspace store tests cover media storage outside project roots.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";

src/media/store.redirect.test.ts

@@ -1,3 +1,4 @@
+// Media store redirect tests cover redirected media paths and lookup behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { PassThrough } from "node:stream";

src/media/store.runtime.ts

@@ -1,3 +1,4 @@
+// Media store runtime facade loads filesystem-safe store implementation.
 import "../infra/fs-safe-defaults.js";
 import {
   FsSafeError,

src/media/store.test.ts

@@ -1,3 +1,4 @@
+// Media store tests cover persisted media records and local file storage.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";

src/media/store.ts

@@ -1,3 +1,4 @@
+// Media store persists loaded media files and metadata for later references.
 import "../infra/fs-safe-defaults.js";
 import crypto from "node:crypto";
 import { createWriteStream } from "node:fs";

src/media/temp-files.ts

@@ -1,3 +1,4 @@
+// Media temp file helpers create and clean up temporary media files.
 import fs from "node:fs/promises";
 
 /** Best-effort temp-file cleanup helper for optional paths from media conversion flows. */

src/media/video-dimensions.test.ts

@@ -1,3 +1,4 @@
+// Video dimension tests cover ffprobe parsing and fallback behavior.
 import { describe, expect, it, vi } from "vitest";
 import { parseFfprobeVideoDimensions, probeVideoDimensions } from "./video-dimensions.js";
 

src/media/video-dimensions.ts

@@ -1,3 +1,4 @@
+// Video dimension helpers read video dimensions through ffprobe.
 import { runFfprobe } from "./ffmpeg-exec.js";
 
 /** Positive video dimensions reported by ffprobe for the first video stream. */

src/media/web-media.test.ts

@@ -1,3 +1,4 @@
+// Web media tests cover loading media for web UI and browser surfaces.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/media/web-media.ts

@@ -1,3 +1,4 @@
+// Web media helpers load local and remote media for web-facing surfaces.
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 import { maxBytesForKind, type MediaKind } from "@openclaw/media-core/constants";