@honua/app-platform 0.1.2-beta.0 → 0.1.4-beta.0

package/web-components/export.js

@@ -0,0 +1,719 @@
+/**
+ * The Honua component kit's **export-adapter contract** (issue #683, parent
+ * epic #678; REQ-001/REQ-002/REQ-003).
+ *
+ * ## Why an adapter at all
+ *
+ * `<honua-print-export>` has always offered three actions — print layout,
+ * renderer snapshot, sanitized state JSON — but only browser print was ever
+ * implemented. The other two were *correctly* reported as unsupported rather
+ * than being faked, because producing them safely needs something the
+ * component kit does not have and must not guess at:
+ *
+ * - A **renderer** it is allowed to read pixels from. `canvas.toDataURL()` on a
+ *   WebGL map silently returns a blank image unless the map was created with
+ *   `canvasContextAttributes: { preserveDrawingBuffer: true }` (MapLibre 5 and
+ *   6; earlier majors took a top-level `preserveDrawingBuffer`), and it throws on a canvas tainted by
+ *   cross-origin tiles. Only the application that constructed the map knows
+ *   which of those is true, and only it can decide whether reading those
+ *   pixels is authorized.
+ * - An **authorization boundary**. A map's live state transitively references
+ *   the credentials that made it work: signed tile URLs, `Authorization`
+ *   headers, SAS query strings, OAuth scope detail. Serializing "the current
+ *   state" naively hands all of that to whoever receives the file.
+ *
+ * So export is modelled as an explicit, injected capability. There is no
+ * ambient fallback that "does its best": with no adapter, snapshot and state
+ * export **fail closed** with {@link HonuaCapabilityNotSupportedError} and
+ * produce no bytes at all. That is the whole point — a missing adapter must
+ * never degrade into a silent, partially-credentialed artifact.
+ *
+ * ## The four things the contract makes explicit (REQ-001)
+ *
+ * 1. **Capability** — {@link HonuaExportAdapter.describeCapabilities} declares
+ *    exactly which kinds the adapter implements. A kind it does not declare is
+ *    refused before the adapter is called; a kind it declares but does not
+ *    implement is a *reported* contract violation, never a silent no-op.
+ * 2. **Ownership** — every result carries {@link HonuaExportResult.ownership}
+ *    and an always-present {@link HonuaExportResult.release}. `bytes` handed to
+ *    the caller are the caller's to keep and remain valid after `release()`;
+ *    `release()` frees only adapter-held resources (object URLs, offscreen
+ *    canvases, server-side render jobs). Callers can therefore always call it
+ *    exactly once, unconditionally, in a `finally`.
+ * 3. **Cancellation** — an {@link AbortSignal} is checked before the adapter
+ *    runs, forwarded to it, and re-checked after it returns; a cancelled export
+ *    releases whatever the adapter produced and yields `status: "cancelled"`
+ *    with no bytes.
+ * 4. **Error reporting** — the runner never throws. It returns a discriminated
+ *    {@link HonuaExportResult} whose `status` is one of
+ *    `ready`/`unsupported`/`cancelled`/`error`, with a redacted `message` and
+ *    the structured `error` for programmatic handling. Elements can render the
+ *    envelope directly; callers who prefer exceptions use
+ *    {@link assertHonuaExportReady}.
+ *
+ * ## Redaction is not the adapter's job (REQ-002)
+ *
+ * The runner sanitizes state **before** the adapter is invoked, so an adapter
+ * — including a third-party or server-side one — never receives credential
+ * material in the first place. It then re-scans everything the adapter returned
+ * (bytes, text, filename hint, fidelity warnings) and refuses to emit an
+ * artifact that fails the scan. Both layers live in
+ * {@link "./export-redaction.js"}; see that module for the two-layer model.
+ *
+ * ## Provenance travels with the artifact (REQ-003)
+ *
+ * Attribution, license notices, scale, export timestamp, data-freshness, and
+ * fidelity warnings are assembled by the runner from the map package and
+ * controller state, handed to the adapter, and echoed on the result. Where a
+ * source declares attribution, the export **cannot** drop it: an artifact
+ * missing required attribution fails closed exactly like a credential leak,
+ * because shipping an unattributed map is a licence violation, not a cosmetic
+ * defect.
+ *
+ * ## Bundle posture (NFR-001)
+ *
+ * This module and its redaction sibling import nothing but the SDK's own error
+ * base and types. No renderer, PDF writer, image encoder, localization
+ * framework, or test-only peer is referenced, statically or dynamically —
+ * every one of those lives on the application side of the adapter seam. The
+ * built-in adapters here are thin structural shims over objects the caller
+ * already owns.
+ *
+ * @module
+ */
+import { HonuaSdkError } from "../core/error-envelope.js";
+import { HonuaAbortError, HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { HonuaExportSafetyError, assertCredentialFreeExportBytes, assertCredentialFreeExportText, redactHonuaExportText, sanitizeHonuaExportFilename, sanitizeHonuaExportState, } from "./export-redaction.js";
+/** Protocol label used in capability errors raised by the export pipeline. */
+const EXPORT_PROTOCOL = "honua-app-platform-export";
+/** Every export kind, in a stable order. */
+export const HONUA_EXPORT_KINDS = Object.freeze(["print", "snapshot", "state"]);
+/** Thrown by {@link assertHonuaExportReady} and used to wrap adapter faults. */
+export class HonuaExportError extends HonuaSdkError {
+    status;
+    constructor(status, message, options = {}) {
+        super("app.export-failed", message, options);
+        this.name = "HonuaExportError";
+        this.status = status;
+    }
+}
+// ── provenance ───────────────────────────────────────────────────────────
+/** `1:24,000`-style approximate scale for a web-mercator viewport at 96 DPI. */
+export function approximateHonuaScaleLabel(viewport) {
+    const zoom = viewport?.zoom;
+    if (!Number.isFinite(zoom))
+        return undefined;
+    const latitude = viewport?.center?.[1] ?? 0;
+    const metersPerPixel = (156543.03392 * Math.cos((latitude * Math.PI) / 180)) / 2 ** Number(zoom);
+    const scale = Math.max(1, Math.round(metersPerPixel * 96 * 39.37));
+    return `1:${scale.toLocaleString("en-US")}`;
+}
+/** Attribution strings a map package's own bindings and style sources declare. */
+function collectDeclaredAttribution(mapPackage) {
+    const attribution = new Set();
+    for (const binding of mapPackage?.sourceBindings ?? []) {
+        if (typeof binding.attribution === "string" && binding.attribution.trim().length > 0) {
+            attribution.add(redactHonuaExportText(binding.attribution.trim()).slice(0, 512));
+        }
+    }
+    const styleSources = mapPackage?.mapSpec?.sources;
+    if (styleSources && typeof styleSources === "object") {
+        for (const source of Object.values(styleSources)) {
+            const value = source?.attribution;
+            if (typeof value === "string" && value.trim().length > 0) {
+                attribution.add(redactHonuaExportText(value.trim()).slice(0, 512));
+            }
+        }
+    }
+    return [...attribution];
+}
+/** Licence notices declared on the map package (`license`, `licence`, or `metadata.license`). */
+function collectDeclaredLicenseNotices(mapPackage) {
+    const notices = new Set();
+    const candidates = [
+        mapPackage?.license,
+        mapPackage?.licence,
+        mapPackage?.metadata?.license,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim().length > 0) {
+            notices.add(redactHonuaExportText(candidate.trim()).slice(0, 512));
+        }
+    }
+    return [...notices];
+}
+/**
+ * Assembles the provenance block for an export (REQ-003) from the map package
+ * and controller state, unioned with anything the accepted plan additionally
+ * requires. Every string is redacted, because attribution text is
+ * caller-supplied and has appeared with a signed URL in it in the wild.
+ */
+export function buildHonuaExportProvenance(state, sanitized, options = {}) {
+    const attribution = new Set(collectDeclaredAttribution(state?.mapPackage));
+    for (const entry of options.requiredAttribution ?? []) {
+        const trimmed = redactHonuaExportText(entry.trim()).slice(0, 512);
+        if (trimmed.length > 0)
+            attribution.add(trimmed);
+    }
+    const licenseNotices = new Set(collectDeclaredLicenseNotices(state?.mapPackage));
+    for (const entry of options.requiredLicenseNotices ?? []) {
+        const trimmed = redactHonuaExportText(entry.trim()).slice(0, 512);
+        if (trimmed.length > 0)
+            licenseNotices.add(trimmed);
+    }
+    const fidelityWarnings = new Set((options.fidelityWarnings ?? []).map((warning) => redactHonuaExportText(warning).slice(0, 512)));
+    // A withheld non-exportable source is a fidelity loss the artifact must
+    // admit to; silently shipping a map that is missing a layer is worse than
+    // shipping one that says so.
+    const omitted = sanitized.sources.filter((source) => source.omitted).map((source) => source.sourceId);
+    if (omitted.length > 0) {
+        fidelityWarnings.add(`${omitted.length} source(s) marked non-exportable were omitted from this export: ${omitted.join(", ")}.`);
+    }
+    const provenance = {
+        exportedAt: options.exportedAt ?? new Date().toISOString(),
+        attribution: [...attribution],
+        licenseNotices: [...licenseNotices],
+        fidelityWarnings: [...fidelityWarnings],
+        generator: "@honua/sdk-js app-platform component kit",
+    };
+    const scaleLabel = approximateHonuaScaleLabel(sanitized.viewport ?? state?.viewport);
+    if (scaleLabel)
+        provenance.scaleLabel = scaleLabel;
+    if (sanitized.refreshedAt)
+        provenance.dataFreshnessAt = sanitized.refreshedAt;
+    if (typeof sanitized.stale === "boolean")
+        provenance.stale = sanitized.stale;
+    if (sanitized.packageId)
+        provenance.packageId = sanitized.packageId;
+    return provenance;
+}
+/**
+ * Fail-closed provenance check (REQ-003): every attribution string and licence
+ * notice a source or the accepted plan declares must be present on the
+ * provenance that ships with the artifact.
+ *
+ * This exists because provenance is the one part of an export a well-meaning
+ * adapter or caller is most likely to "simplify away". Dropping attribution is
+ * a licence breach, so it is enforced with the same severity as a credential
+ * leak rather than logged as a warning.
+ */
+export function assertHonuaExportProvenanceComplete(provenance, required) {
+    const missingAttribution = required.attribution.filter((entry) => !provenance.attribution.includes(entry));
+    const missingLicenses = required.licenseNotices.filter((entry) => !provenance.licenseNotices.includes(entry));
+    if (missingAttribution.length === 0 && missingLicenses.length === 0)
+        return;
+    throw new HonuaExportSafetyError(`Export is missing required provenance: ${[...missingAttribution, ...missingLicenses].join("; ")}.`, "unsupported-value");
+}
+// ── the runner ───────────────────────────────────────────────────────────
+const ADAPTER_METHODS = {
+    print: "print",
+    snapshot: "snapshot",
+    state: "exportState",
+};
+function noopRelease() {
+    return Promise.resolve();
+}
+/** Wraps a payload's `release` so it runs at most once and never rejects. */
+function onceRelease(release) {
+    if (!release)
+        return noopRelease;
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            await release();
+        }
+        catch {
+            // A failing release is not worth surfacing over the export's own
+            // outcome; the resource is the adapter's to leak.
+        }
+    };
+}
+function unsupported(kind, adapterId, provenance, redactions, capability, message) {
+    const redactedAdapterId = adapterId === undefined ? undefined : redactHonuaExportText(adapterId);
+    const redactedMessage = redactHonuaExportText(redactedAdapterId && adapterId ? message.replaceAll(adapterId, redactedAdapterId) : message);
+    return {
+        kind,
+        status: "unsupported",
+        adapterId,
+        provenance,
+        redactions,
+        ownership: "none",
+        release: noopRelease,
+        message: redactedMessage,
+        error: new HonuaCapabilityNotSupportedError(capability, EXPORT_PROTOCOL, adapterId),
+    };
+}
+function failed(kind, adapterId, provenance, redactions, error, ownership) {
+    return {
+        kind,
+        status: "error",
+        adapterId,
+        provenance,
+        redactions,
+        ownership,
+        release: noopRelease,
+        message: redactHonuaExportText(error.message),
+        error,
+    };
+}
+/**
+ * Copies adapter bytes into a buffer the caller owns outright.
+ *
+ * Adapters routinely hand back a view onto a canvas-backed or pooled buffer
+ * they will reuse or free. Copying is what makes the ownership contract
+ * ("`bytes` stay valid after `release()`") true rather than aspirational.
+ */
+function adoptBytes(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy;
+}
+/**
+ * Runs one export end to end. Never throws: every failure mode — no adapter,
+ * undeclared kind, missing method, adapter exception, cancellation, unsafe
+ * artifact, missing provenance — comes back as a {@link HonuaExportResult}.
+ *
+ * @example Fail closed with no adapter
+ * ```ts doc-test=skip reason="illustrative excerpt over an ambient controller state"
+ * const result = await runHonuaExport({ kind: "snapshot", state });
+ * result.status;        // "unsupported"
+ * result.bytes;         // undefined — no partial artifact is ever produced
+ * result.error?.sdkCode // "core.capability-not-supported"
+ * ```
+ */
+export async function runHonuaExport(request) {
+    const { kind, adapter } = request;
+    const sanitization = sanitizeHonuaExportState(request.state, request.nonExportableSourceIds ? { nonExportableSourceIds: request.nonExportableSourceIds } : {});
+    const requiredAttribution = [
+        ...collectDeclaredAttribution(request.state?.mapPackage),
+        ...(request.requiredAttribution ?? []).map((entry) => redactHonuaExportText(entry.trim()).slice(0, 512)),
+    ].filter((entry) => entry.length > 0);
+    const requiredLicenseNotices = [
+        ...collectDeclaredLicenseNotices(request.state?.mapPackage),
+        ...(request.requiredLicenseNotices ?? []).map((entry) => redactHonuaExportText(entry.trim()).slice(0, 512)),
+    ].filter((entry) => entry.length > 0);
+    const baseProvenance = buildHonuaExportProvenance(request.state, sanitization.state, {
+        ...(request.requiredAttribution ? { requiredAttribution: request.requiredAttribution } : {}),
+        ...(request.requiredLicenseNotices ? { requiredLicenseNotices: request.requiredLicenseNotices } : {}),
+        ...(request.exportedAt ? { exportedAt: request.exportedAt } : {}),
+    });
+    const redactions = sanitization.redactions;
+    const title = request.title === undefined ? undefined : redactHonuaExportText(request.title).slice(0, 256);
+    if (!adapter) {
+        return unsupported(kind, undefined, baseProvenance, redactions, `export:${kind}`, `${describeKind(kind)} requires an explicit export adapter. Without one the component kit cannot read renderer pixels or authorize a state export, so it refuses rather than emitting a partial or credentialed artifact.`);
+    }
+    let capabilities;
+    try {
+        capabilities = adapter.describeCapabilities();
+    }
+    catch (cause) {
+        return failed(kind, typeof adapter.id === "string" ? adapter.id : undefined, baseProvenance, redactions, new HonuaExportError("error", "Export adapter failed to describe its capabilities.", { cause }), "none");
+    }
+    // Validated rather than trusted, and validated *inside* the guarded region:
+    // an adapter that returns undefined, null, or an object without a `kinds`
+    // array used to be dereferenced here and reject the whole call with a
+    // TypeError, breaking this function's one guarantee — that it always resolves
+    // to a structured result. A malformed capability declaration is a contract
+    // violation by the adapter and is reported as one.
+    const declaredId = capabilities?.adapterId;
+    const adapterId = (typeof declaredId === "string" && declaredId) || adapter.id || "unknown-adapter";
+    const declaredKinds = capabilities?.kinds;
+    if (!capabilities || typeof capabilities !== "object" || !Array.isArray(declaredKinds)) {
+        return failed(kind, typeof adapterId === "string" ? adapterId : undefined, baseProvenance, redactions, new HonuaExportError("error", `Export adapter "${String(adapterId)}" returned a malformed capability declaration; describeCapabilities() must return an object with a kinds array.`), "none");
+    }
+    if (!declaredKinds.includes(kind)) {
+        return unsupported(kind, adapterId, baseProvenance, redactions, `export:${kind}`, `Export adapter "${adapterId}" does not declare the "${kind}" export kind.`);
+    }
+    const method = adapter[ADAPTER_METHODS[kind]];
+    if (typeof method !== "function") {
+        return unsupported(kind, adapterId, baseProvenance, redactions, `export:${kind}`, `Export adapter "${adapterId}" declares the "${kind}" kind but does not implement ${String(ADAPTER_METHODS[kind])}().`);
+    }
+    if (request.signal?.aborted) {
+        return {
+            kind,
+            status: "cancelled",
+            adapterId,
+            provenance: baseProvenance,
+            redactions,
+            ownership: "released",
+            release: noopRelease,
+            message: "Export was cancelled before the adapter ran.",
+            error: new HonuaAbortError("Export was cancelled before the adapter ran."),
+        };
+    }
+    const context = {
+        kind,
+        title,
+        provenance: baseProvenance,
+        state: sanitization.state,
+        signal: request.signal,
+        mediaType: request.mediaType,
+    };
+    let payload;
+    try {
+        payload = await method.call(adapter, context);
+    }
+    catch (cause) {
+        if (request.signal?.aborted || isAbortLike(cause)) {
+            return {
+                kind,
+                status: "cancelled",
+                adapterId,
+                provenance: baseProvenance,
+                redactions,
+                ownership: "released",
+                release: noopRelease,
+                message: "Export was cancelled.",
+                error: new HonuaAbortError("Export was cancelled."),
+            };
+        }
+        // An adapter that already speaks the SDK's error envelope has said
+        // something specific and actionable ("the canvas is not readable because
+        // the map lacks preserveDrawingBuffer"); wrapping that in a generic message
+        // would throw away the only useful part. Its message is redacted by
+        // `failed()` like any other.
+        return failed(kind, adapterId, baseProvenance, redactions, cause instanceof HonuaSdkError
+            ? cause
+            : new HonuaExportError("error", `Export adapter "${adapterId}" failed to produce a ${kind} artifact.`, {
+                cause,
+            }), "none");
+    }
+    const release = onceRelease(payload?.release);
+    if (!payload || typeof payload !== "object") {
+        await release();
+        return failed(kind, adapterId, baseProvenance, redactions, new HonuaExportError("error", `Export adapter "${adapterId}" returned no payload for the ${kind} export.`), "released");
+    }
+    if (request.signal?.aborted) {
+        await release();
+        return {
+            kind,
+            status: "cancelled",
+            adapterId,
+            provenance: baseProvenance,
+            redactions,
+            ownership: "released",
+            release: noopRelease,
+            message: "Export was cancelled; the adapter's resources were released.",
+            error: new HonuaAbortError("Export was cancelled after the adapter produced an artifact."),
+        };
+    }
+    try {
+        const result = finalize(kind, adapterId, payload, baseProvenance, redactions, release, { attribution: requiredAttribution, licenseNotices: requiredLicenseNotices }, request.requireEmbeddedProvenance === true);
+        return result;
+    }
+    catch (cause) {
+        await release();
+        const error = cause instanceof HonuaExportSafetyError
+            ? cause
+            : new HonuaExportError("error", `Export adapter "${adapterId}" produced an unusable ${kind} artifact.`, {
+                cause,
+            });
+        return failed(kind, adapterId, baseProvenance, redactions, error, "released");
+    }
+}
+function describeKind(kind) {
+    if (kind === "snapshot")
+        return "Snapshot export";
+    if (kind === "state")
+        return "State export";
+    return "Print export";
+}
+function isAbortLike(cause) {
+    const name = cause?.name;
+    return name === "AbortError" || cause instanceof HonuaAbortError;
+}
+/**
+ * Validates and adopts an adapter payload. Throws on anything unsafe — the
+ * caller turns that into a `status: "error"` result after releasing the
+ * adapter's resources.
+ */
+function finalize(kind, adapterId, payload, baseProvenance, redactions, release, required, requireEmbeddedProvenance) {
+    const projectedMediaType = projectMediaType(payload.mediaType);
+    const adapterWarnings = (payload.fidelityWarnings ?? []).map((warning) => redactHonuaExportText(String(warning)).slice(0, 512));
+    const warnings = new Set([...baseProvenance.fidelityWarnings, ...adapterWarnings]);
+    if (projectedMediaType.violation && projectedMediaType.mediaType.length > 0) {
+        warnings.add(`Export adapter "${adapterId}": ${projectedMediaType.violation}.`);
+    }
+    // REQ-003: whether the artifact's *bytes* carry the required attribution is a
+    // separate fact from whether the export knows the attribution, and conflating
+    // them is how an unattributed image ships. An adapter must say which it did;
+    // the safe default for an artifact that carries a body is "did not".
+    const requiresProvenance = required.attribution.length > 0 || required.licenseNotices.length > 0;
+    const provenanceEmbedded = payload.sideEffectOnly === true || payload.provenanceEmbedded === true;
+    if (requiresProvenance && !provenanceEmbedded) {
+        warnings.add(`This artifact's bytes do not carry the attribution and licence notices its sources require (${[
+            ...required.attribution,
+            ...required.licenseNotices,
+        ].join("; ")}). The caller must present them alongside the artifact wherever it is published.`);
+    }
+    const provenance = { ...baseProvenance, fidelityWarnings: [...warnings] };
+    assertHonuaExportProvenanceComplete(provenance, required);
+    // The strict mode, for callers who cannot present provenance out of band.
+    if (requireEmbeddedProvenance && requiresProvenance && !provenanceEmbedded) {
+        throw new HonuaExportSafetyError(`Export adapter "${adapterId}" cannot embed the required attribution into the ${kind} artifact, and requireEmbeddedProvenance was set. Refusing to emit an artifact whose bytes would travel without the attribution its sources require.`, "unsupported-value");
+    }
+    if (payload.sideEffectOnly === true) {
+        return {
+            kind,
+            status: "ready",
+            adapterId,
+            sideEffectOnly: true,
+            provenance,
+            provenanceEmbedded,
+            redactions,
+            // A side-effect export can still hold resources (a print stylesheet
+            // injected into the document, an off-screen render frame). Reporting
+            // "none" here told documented callers to skip cleanup and leaked it.
+            ownership: payload.release ? "caller-releases" : "none",
+            release,
+        };
+    }
+    if (projectedMediaType.mediaType.length === 0) {
+        throw new HonuaExportError("error", `Export adapter "${adapterId}" returned an artifact with no media type.`);
+    }
+    const mediaType = projectedMediaType.mediaType;
+    const result = {
+        kind,
+        status: "ready",
+        adapterId,
+        filename: sanitizeHonuaExportFilename({
+            ...(payload.filenameHint === undefined ? {} : { title: payload.filenameHint }),
+            mediaType,
+        }),
+        mediaType,
+        provenance,
+        provenanceEmbedded,
+        redactions,
+        ownership: payload.release ? "caller-releases" : "none",
+        release,
+    };
+    if (payload.bytes instanceof Uint8Array) {
+        // Scanned two ways, because "binary" is not a security boundary. A buffer
+        // that decodes cleanly as UTF-8 (SVG, JSON, HTML) is scanned as text; every
+        // buffer, including a genuine PNG or PDF that will never decode, also has
+        // its printable runs extracted and scanned, so a token inside a PNG tEXt
+        // chunk, a JPEG comment, or PDF/XMP metadata cannot ride out under cover of
+        // the surrounding binary.
+        const decoded = decodeUtf8Strict(payload.bytes);
+        if (decoded !== undefined)
+            assertCredentialFreeExportText(decoded, `${kind} export bytes`);
+        assertCredentialFreeExportBytes(payload.bytes, `${kind} export bytes`);
+        result.bytes = adoptBytes(payload.bytes);
+    }
+    else if (typeof payload.text === "string") {
+        assertCredentialFreeExportText(payload.text, `${kind} export text`);
+        result.text = payload.text;
+    }
+    else {
+        throw new HonuaExportError("error", `Export adapter "${adapterId}" returned neither bytes nor text for the ${kind} export.`);
+    }
+    for (const warning of provenance.fidelityWarnings) {
+        assertCredentialFreeExportText(warning, "export fidelity warning");
+    }
+    return result;
+}
+/** Fallback for a media type the adapter got wrong; deliberately inert. */
+const SAFE_FALLBACK_MEDIA_TYPE = "application/octet-stream";
+/** RFC 9110 token characters, the only thing allowed in a type, subtype, or parameter name. */
+const MEDIA_TYPE_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+/**
+ * Parameters an export media type may carry. Everything else is dropped: a
+ * media type is echoed onto the result, onto the `honua-export` event, and into
+ * a `Content-Type` header by most callers, so an adapter-controlled parameter
+ * bag is a credential channel (`text/plain; token=...`) and a header-injection
+ * channel. `charset` is the only parameter an export artifact legitimately
+ * needs, and its value is checked against the same token grammar.
+ */
+const MEDIA_TYPE_PARAMETER_ALLOWLIST = new Set(["charset"]);
+/**
+ * Validates an adapter-supplied media type against a strict `type/subtype`
+ * grammar with an allowlisted parameter set, replacing anything else with
+ * {@link SAFE_FALLBACK_MEDIA_TYPE} and reporting the substitution.
+ *
+ * Truncation alone (the previous behavior) is not validation: it bounds length
+ * and nothing else, so a value carrying a token, a newline, or arbitrary
+ * parameters passed straight through to the result and the event detail.
+ */
+function projectMediaType(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { mediaType: "", violation: "no media type" };
+    }
+    const value = raw.slice(0, 255);
+    const [essence, ...parameters] = value.split(";");
+    const [type, subtype, ...extra] = essence.trim().toLowerCase().split("/");
+    if (extra.length > 0 || !MEDIA_TYPE_TOKEN.test(type ?? "") || !MEDIA_TYPE_TOKEN.test(subtype ?? "")) {
+        return {
+            mediaType: SAFE_FALLBACK_MEDIA_TYPE,
+            violation: `media type is not a valid type/subtype; substituted ${SAFE_FALLBACK_MEDIA_TYPE}`,
+        };
+    }
+    const kept = [];
+    let dropped = 0;
+    for (const parameter of parameters) {
+        const separator = parameter.indexOf("=");
+        if (separator < 0) {
+            dropped += 1;
+            continue;
+        }
+        const name = parameter.slice(0, separator).trim().toLowerCase();
+        const parameterValue = parameter
+            .slice(separator + 1)
+            .trim()
+            .replace(/^"|"$/g, "");
+        if (!MEDIA_TYPE_PARAMETER_ALLOWLIST.has(name) || !MEDIA_TYPE_TOKEN.test(parameterValue)) {
+            dropped += 1;
+            continue;
+        }
+        kept.push(`${name}=${parameterValue}`);
+    }
+    const mediaType = [`${type}/${subtype}`, ...kept].join("; ");
+    return dropped === 0
+        ? { mediaType }
+        : { mediaType, violation: `${dropped} disallowed media-type parameter(s) were dropped` };
+}
+function decodeUtf8Strict(bytes) {
+    if (typeof TextDecoder === "undefined")
+        return undefined;
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Throws `result.error` unless the export succeeded; returns the result otherwise. */
+export function assertHonuaExportReady(result) {
+    if (result.status === "ready")
+        return result;
+    throw result.error ?? new HonuaExportError(result.status, result.message ?? "Export did not complete.");
+}
+const DATA_URL_PREFIX = /^data:([^;,]{1,128})?(;base64)?,/i;
+function decodeDataUrl(dataUrl) {
+    const match = DATA_URL_PREFIX.exec(dataUrl);
+    if (!match)
+        throw new HonuaExportError("error", "Renderer returned a value that is not a data URL.");
+    const mediaType = match[1] || "image/png";
+    const body = dataUrl.slice(match[0].length);
+    if (match[2]) {
+        const binary = typeof atob === "function" ? atob(body) : Buffer.from(body, "base64").toString("binary");
+        const bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1)
+            bytes[index] = binary.charCodeAt(index);
+        return { mediaType, bytes };
+    }
+    return { mediaType, bytes: new TextEncoder().encode(decodeURIComponent(body)) };
+}
+/**
+ * Builds an export adapter from capabilities the application explicitly grants.
+ *
+ * Everything here is structural: no `maplibre-gl`, `cesium`, PDF writer, or
+ * image encoder is imported, so wiring an adapter costs a consumer bundle
+ * nothing beyond the object it passes in (NFR-001).
+ *
+ * @example
+ * ```ts doc-test=skip reason="requires a live MapLibre map instance"
+ * const adapter = createHonuaExportAdapter({
+ *   id: "my-app",
+ *   // map created with canvasContextAttributes: { preserveDrawingBuffer: true }
+ *   snapshot: { getCanvas: () => map.getCanvas() },
+ *   state: true,
+ * });
+ * printExportElement.exportAdapter = adapter;
+ * ```
+ */
+export function createHonuaExportAdapter(options) {
+    const kinds = [];
+    if (options.print)
+        kinds.push("print");
+    if (options.snapshot)
+        kinds.push("snapshot");
+    if (options.state)
+        kinds.push("state");
+    const snapshotMediaTypes = options.snapshot ? [options.snapshot.mediaType ?? "image/png"] : undefined;
+    const adapter = {
+        id: options.id,
+        describeCapabilities: () => ({
+            adapterId: options.id,
+            kinds: [...kinds],
+            cancellable: true,
+            ...(snapshotMediaTypes ? { snapshotMediaTypes } : {}),
+        }),
+    };
+    if (options.print)
+        adapter.print = options.print;
+    if (options.snapshot) {
+        const source = options.snapshot;
+        adapter.snapshot = (context) => {
+            const canvas = source.getCanvas();
+            if (!canvas) {
+                throw new HonuaExportError("error", "The renderer canvas is not currently readable, so no snapshot was produced. A map must be created with canvasContextAttributes: { preserveDrawingBuffer: true } for its pixels to be readable.");
+            }
+            const mediaType = context.mediaType ?? source.mediaType ?? "image/png";
+            if (typeof canvas.toDataURL !== "function") {
+                throw new HonuaExportError("error", "The supplied renderer canvas does not implement toDataURL().");
+            }
+            const decoded = decodeDataUrl(canvas.toDataURL(mediaType));
+            return {
+                mediaType: decoded.mediaType,
+                bytes: decoded.bytes,
+                filenameHint: context.title ?? context.provenance.packageId ?? "snapshot",
+                fidelityWarnings: source.fidelityWarnings ?? [],
+                // Reading a canvas captures the map's pixels and nothing else: MapLibre
+                // renders attribution as DOM siblings of the canvas, so it is provably
+                // absent from these bytes. Declaring `true` here would make the result
+                // claim an attribution guarantee the image does not carry, which is the
+                // licence-breaking failure REQ-003 exists to prevent. The runner turns
+                // this into an explicit fidelity warning naming what the caller must
+                // present, or a hard failure under `requireEmbeddedProvenance`.
+                // An adapter that composites a watermark or footer should declare true.
+                provenanceEmbedded: source.provenanceEmbedded === true,
+            };
+        };
+    }
+    if (options.state) {
+        const custom = typeof options.state === "function" ? options.state : undefined;
+        adapter.exportState =
+            custom ??
+                ((context) => ({
+                    mediaType: "application/json",
+                    text: JSON.stringify({ ...context.state, provenance: context.provenance }, null, 2),
+                    filenameHint: context.title ?? context.provenance.packageId ?? "state",
+                }));
+    }
+    return adapter;
+}
+/**
+ * The browser-print adapter: the one export the component kit can serve without
+ * application help, because `window.print()` reads no pixels and serializes no
+ * state — the browser prints what it already renders, under the user's own
+ * session.
+ *
+ * It is a *default* for `print` only. Snapshot and state export deliberately
+ * have no equivalent built-in, because both require reading privileged data.
+ */
+export function createBrowserPrintExportAdapter(windowLike = typeof window === "undefined" ? undefined : window) {
+    return {
+        id: "honua-browser-print",
+        describeCapabilities: () => ({
+            adapterId: "honua-browser-print",
+            kinds: windowLike && typeof windowLike.print === "function" ? ["print"] : [],
+            cancellable: false,
+        }),
+        print: () => {
+            if (!windowLike || typeof windowLike.print !== "function") {
+                throw new HonuaExportError("error", "Window printing is unavailable in this environment.");
+            }
+            windowLike.print();
+            return {
+                mediaType: "application/vnd.honua.print-dialog",
+                sideEffectOnly: true,
+                fidelityWarnings: [
+                    "Browser print reproduces the on-screen layout only; page breaks, scale, and layer legibility are controlled by the print stylesheet, not by the map.",
+                ],
+            };
+        },
+    };
+}