@flighthq/swf 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/swfDocument.js

@@ -4,17 +4,18 @@ import { createClipRegionFromContours, createClipRegionFromPath } from '@flighth
 import { getDecompressor } from '@flighthq/compression/contract';
 import { createMatrix, inverseMatrix, matrixTransformPointXY, multiplyMatrix } from '@flighthq/geometry/contract';
 import { createEmbeddedImageResourceReference } from '@flighthq/image/contract';
+import { reportImportDiagnostic } from '@flighthq/importdiagnostics/contract';
 import { addMovieClipFrameScript, createMovieClip, setMovieClipSource } from '@flighthq/movieclip/contract';
 import { addNodeChild, addNodeOrderListEntry, applyNodeOrderList, clearNodeOrderList, createNodeOrderList, getNodeRuntime, invalidateNodeAppearance, invalidateNodeLocalBounds, removeNodeChild, setNodeColorAdjustments, setNodeLocalMatrix, } from '@flighthq/node/contract';
 import { createScene2DDocument, createScene2DSlotReference, registerScene2DDocumentImporter, } from '@flighthq/scene2d-resources/contract';
 import { createDisplayObject, createSprite, setNode2DClip } from '@flighthq/scene2d/contract';
 import { copyShapeCommands, createScale9Shape, createShape, getShapeFillRegions, setMorphShapeProgress, } from '@flighthq/shape/contract';
-import { createSampler, createTexture, setTextureSource } from '@flighthq/texture/contract';
-import { AdvancedBlendMode, BlendMode, Compression, MorphShapeKind, TimelineAudioCueKind, TimelineStreamAudioCueKind, } from '@flighthq/types/contract';
-import { createSwfLosslessBitmap } from './swfBitmap';
+import { createSampler, createTexture } from '@flighthq/texture/contract';
+import { AdvancedBlendMode, BlendMode, Compression, CompressionFraming, ImportDiagnosticSeverity, MorphShapeKind, TimelineAudioCueKind, TimelineStreamAudioCueKind, } from '@flighthq/types/contract';
 import { readSwfEditTextFactory } from './swfEditText';
 import { readSwfFilterList } from './swfFilter';
 import { readSwfAbcFrameScripts, readSwfFrameActions } from './swfFrameAction';
+import { SWF_LOSSLESS_ALPHA_MIME_TYPE, SWF_LOSSLESS_MIME_TYPE } from './swfImageDecoder';
 import { createSwfMorphShape } from './swfMorphShape';
 import { SwfReader } from './swfReader';
 import { createSwfShape } from './swfShape';
@@ -22,23 +23,23 @@ import { createSwfTextShape, readSwfFontGlyphOutlineSource } from './swfText';
 // Recovers every embedded DefineFont/2/3 as the generic, glyph-index-keyed outline seam. The map key
 // is the SWF character id used by DefineText and DefineEditText. This is a separate parse entry from
 // Scene2D construction so callers that only need embedded fonts do not have to retain a document.
-export function createGlyphOutlineSourcesFromSwf(source) {
-    const file = readSwfFile(source);
+export function createGlyphOutlineSourcesFromSwf(source, diagnostics) {
+    const file = readSwfFile(source, diagnostics);
     return file === null ? null : new Map(file.parsed.fontOutlineSources);
 }
 // The document alone, for a caller that wants the graph and nothing else — the importer registry among
 // them. A file whose placements carry an advanced blend or a filter list still imports fully here; what
 // it loses is the report of them, which is what createScene2DImportFromSwf returns.
-export function createScene2DFromSwf(source) {
-    return createScene2DImportFromSwf(source)?.document ?? null;
+export function createScene2DFromSwf(source, diagnostics) {
+    return createScene2DImportFromSwf(source, diagnostics)?.document ?? null;
 }
 // The full import: the document, plus the placement appearance no node can carry. SWF puts a blend mode
 // and a filter list on the same record as the matrix, and Flight expresses neither on a node — an
 // advanced blend needs a BlendEffect and an effect is a descriptor a caller runs explicitly, since
 // `displayObject.filters` is an anti-goal. Both therefore travel beside the document instead of being
 // dropped at the seam or silently flattened onto a node.
-export function createScene2DImportFromSwf(source) {
-    const file = readSwfFile(source);
+export function createScene2DImportFromSwf(source, diagnostics) {
+    const file = readSwfFile(source, diagnostics);
     if (file === null)
         return null;
     const { frameRate, parsed, stageBounds } = file;
@@ -46,17 +47,21 @@ export function createScene2DImportFromSwf(source) {
     const instantiation = {
         activeSymbols: new Set(),
         appearances: [],
+        diagnostics,
         frameRate: frameRate > 0 ? frameRate : null,
         resolvingBounds: new Set(),
         resolvedBounds: new Map(),
     };
     const root = createSwfTimelineNode(parsed.timeline, stageBounds, parsed, slots, instantiation, 0);
-    if (root === null)
+    if (root === null) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.timeline-instantiation-failed', 'createScene2DImportFromSwf');
         return null;
-    fillSwfLosslessBitmapTextures(parsed);
+    }
+    const imageResources = createSwfImageResources(parsed);
     return {
         appearances: instantiation.appearances,
-        document: createScene2DDocument(root, slots, 'swf', parsed.backgroundColor, createSwfImageResources(parsed), createSwfAudioResources(parsed)),
+        document: createScene2DDocument(root, slots, 'swf', parsed.backgroundColor, imageResources.resources, createSwfAudioResources(parsed)),
+        jpegAlphaPayloads: createSwfJpegAlphaPayloads(parsed, imageResources.references),
     };
 }
 // Instantiates a symbol the file exported by linkage name but never placed on a timeline. A library
@@ -70,8 +75,8 @@ export function createScene2DImportFromSwf(source) {
 // Anything less would hand back artwork whose bitmaps could never be paired with their pixels, since
 // each call parses afresh and its Textures are its own. `backgroundColor` stays null: the stage colour
 // belongs to the stage, and a symbol instantiated into someone else's scene is not it.
-export function createScene2DSymbolFromSwf(source, linkageName) {
-    const file = readSwfFile(source);
+export function createScene2DSymbolFromSwf(source, linkageName, diagnostics) {
+    const file = readSwfFile(source, diagnostics);
     if (file === null)
         return null;
     const { frameRate, parsed } = file;
@@ -80,12 +85,19 @@ export function createScene2DSymbolFromSwf(source, linkageName) {
         if (name === linkageName)
             characterId = id;
     }
-    if (characterId < 0)
+    // A linkage name nothing exports is the caller naming a symbol this file does not have — worth telling
+    // them apart from a file that failed to parse, since both come back null.
+    if (characterId < 0) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.unknown-linkage-name', 'createScene2DSymbolFromSwf', {
+            linkageName,
+        });
         return null;
+    }
     const slots = [];
     const instantiation = {
         activeSymbols: new Set(),
         appearances: [],
+        diagnostics,
         frameRate: frameRate > 0 ? frameRate : null,
         resolvingBounds: new Set(),
         resolvedBounds: new Map(),
@@ -93,8 +105,7 @@ export function createScene2DSymbolFromSwf(source, linkageName) {
     const root = createSwfSymbolNode(parsed, characterId, slots, instantiation);
     if (root === null)
         return null;
-    fillSwfLosslessBitmapTextures(parsed);
-    return createScene2DDocument(root, slots, 'swf', null, createSwfImageResources(parsed), createSwfAudioResources(parsed));
+    return createScene2DDocument(root, slots, 'swf', null, createSwfImageResources(parsed).resources, createSwfAudioResources(parsed));
 }
 // Every linkage name the file exported, whether or not the symbol was ever placed. Pair with
 // `createScene2DSymbolFromSwf` to instantiate one.
@@ -105,58 +116,51 @@ export function readSwfExportedSymbolNames(source) {
 export function registerSwfScene2DDocumentImporter(registry) {
     registerScene2DDocumentImporter(registry, 'swf', matchesSwfDocument, (source) => createScene2DFromSwf(source));
 }
-function readSwfFile(source) {
-    const uncompressed = uncompressSwfSource(source);
+function readSwfFile(source, diagnostics) {
+    const uncompressed = uncompressSwfSource(source, diagnostics);
     if (uncompressed === null)
         return null;
+    // Every rejection below loses the WHOLE document, and each has a distinct cause. Without a report per
+    // cause the caller receives one null from `createScene2DFromSwf` and cannot tell an unregistered
+    // decompressor — which IS reported, upstream — from a truncated header, which was not.
     const header = new SwfReader(uncompressed, 0, uncompressed.length);
     const signature = header.readUint8();
     if (signature !== FWS_SIGNATURE || header.readUint8() !== W_SIGNATURE || header.readUint8() !== S_SIGNATURE) {
+        // Distinct from the container's `swf.invalid-signature`: that one reads the ORIGINAL bytes, this one
+        // reads the decompressed body, whose header the decompressor rewrote. NOTHING CAN REACH THIS TODAY —
+        // an FWS container is returned unchanged and every compressed path writes `FWS_SIGNATURE` into byte 0,
+        // while bytes 1 and 2 were validated before either. The report stays because unreachable-by-
+        // construction is a property of today's two container paths, not of the format: a third path, or a
+        // decompressor that stops rewriting the header, makes it reachable, and silence would return with it.
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.uncompressed-signature-invalid', 'readSwfFile');
         return null;
     }
     const version = header.readUint8();
     const fileLength = header.readUint32();
-    if (!header.valid || version === 0 || fileLength < MIN_SWF_LENGTH || fileLength > uncompressed.length)
+    if (!header.valid || version === 0 || fileLength < MIN_SWF_LENGTH || fileLength > uncompressed.length) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.header-fields-invalid', 'readSwfFile', {
+            declaredLength: fileLength,
+            available: uncompressed.length,
+            version,
+        });
         return null;
+    }
     const body = new SwfReader(uncompressed, SWF_PREFIX_LENGTH, fileLength);
     const stageBounds = readSwfRectangle(body);
-    if (stageBounds === null)
+    if (stageBounds === null) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.stage-bounds-unreadable', 'readSwfFile');
         return null;
+    }
     // Header FrameRate is 8.8 fixed and governs every timeline in the file; the authored FrameCount that
     // follows it is advisory, so the real root frame count comes from the ShowFrame tags themselves.
     const frameRate = body.readUint16() / FIXED_8_8_ONE;
     body.readUint16();
-    if (!body.valid)
+    if (!body.valid) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.header-truncated', 'readSwfFile');
         return null;
-    const parsed = readSwfTags(body);
-    return parsed === null ? null : { frameRate, parsed, stageBounds };
-}
-// Fills in the pixels this package can unpack on its own. A lossless definition is not an image file — it
-// is a raw raster plus zlib — so no generic decoder reaches it, but both halves needed to read it are
-// already here: the shared decompressor the caller registered, and the layout knowledge in swfBitmap. Its
-// pixels therefore resolve at import, and it earns no image resource because there is nothing left to
-// load. The encoded formats leave as references and decode through @flighthq/image later.
-//
-// Only characters something actually samples are unpacked, so a library full of unused bitmaps costs
-// nothing. That is the whole reason this walks the texture map rather than the payload map.
-function fillSwfLosslessBitmapTextures(parsed) {
-    for (const [characterId, variants] of parsed.imageTextures) {
-        if (!isSwfLosslessImage(parsed.images.get(characterId)))
-            continue;
-        const image = parsed.images.get(characterId);
-        if (image === undefined)
-            continue;
-        const bitmap = createSwfLosslessBitmap(image.bytes, image.mimeType === SWF_LOSSLESS_ALPHA_MIME_TYPE);
-        if (bitmap === null)
-            continue;
-        for (const texture of variants.values())
-            setTextureSource(texture, bitmap);
     }
-}
-function isSwfLosslessImage(image) {
-    if (image === undefined)
-        return false;
-    return image.mimeType === SWF_LOSSLESS_MIME_TYPE || image.mimeType === SWF_LOSSLESS_ALPHA_MIME_TYPE;
+    const parsed = readSwfTags(body, diagnostics);
+    return parsed === null ? null : { frameRate, parsed, stageBounds };
 }
 // Presents any container form as the uncompressed bytes the rest of the importer reads. `FWS` is already
 // that and is returned as-is, with no copy. `CWS` and `ZWS` compress everything after the 8-byte header,
@@ -164,32 +168,61 @@ function isSwfLosslessImage(image) {
 // to `FWS` — the declared length already counts uncompressed bytes, so it carries over untouched.
 // Compression the caller has not registered a decompressor for is reported as the document's null
 // sentinel, exactly like a malformed file: the bytes are unreadable either way.
-function uncompressSwfSource(source) {
-    if (source.length < SWF_PREFIX_LENGTH || source[1] !== W_SIGNATURE || source[2] !== S_SIGNATURE)
+function uncompressSwfSource(source, diagnostics) {
+    if (source.length < SWF_PREFIX_LENGTH || source[1] !== W_SIGNATURE || source[2] !== S_SIGNATURE) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.invalid-signature', 'uncompressSwfSource', {
+            length: source.length,
+        });
         return null;
+    }
     const signature = source[0];
     if (signature === FWS_SIGNATURE)
         return source;
     const compression = signature === CWS_SIGNATURE ? Compression.Deflate : signature === ZWS_SIGNATURE ? Compression.Lzma : null;
-    if (compression === null)
+    if (compression === null) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.unknown-container', 'uncompressSwfSource', {
+            signature,
+        });
         return null;
+    }
     const decompress = getDecompressor(compression);
-    if (decompress === null)
+    // Distinct from a malformed body on purpose. Both return the same null sentinel, but a caller that
+    // never registered a decompressor has a file it could read after one registration, while a corrupt
+    // stream is unreadable however the caller is configured — and only the crumb can tell them apart.
+    if (decompress === null) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.no-decompressor-registered', 'uncompressSwfSource', { compression });
         return null;
+    }
     const header = new SwfReader(source, 0, SWF_PREFIX_LENGTH);
     header.readUint32();
     const fileLength = header.readUint32();
-    if (fileLength < MIN_SWF_LENGTH)
+    if (fileLength < MIN_SWF_LENGTH) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.declared-length-too-small', 'uncompressSwfSource', {
+            fileLength,
+        });
         return null;
+    }
     // LZMA puts a compressed length and the 5 property bytes between the header and its stream; zlib starts
     // its stream immediately. Either way the decompressor receives the stream itself.
     const bodyLength = fileLength - SWF_PREFIX_LENGTH;
     const streamStart = compression === Compression.Lzma ? SWF_LZMA_PREFIX_LENGTH : SWF_PREFIX_LENGTH;
-    if (streamStart > source.length)
+    if (streamStart > source.length) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.truncated-container', 'uncompressSwfSource', {
+            length: source.length,
+            streamStart,
+        });
         return null;
-    const body = decompress(source.subarray(streamStart), bodyLength);
-    if (body === null || body.length < bodyLength)
+    }
+    const framing = compression === Compression.Deflate ? CompressionFraming.Rfc1950 : CompressionFraming.Raw;
+    const body = decompress(source.subarray(streamStart), bodyLength, framing);
+    if (body === null || body.length < bodyLength) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Reject, 'swf.decompression-failed', 'uncompressSwfSource', {
+            compression,
+            expected: bodyLength,
+            received: body === null ? -1 : body.length,
+        });
         return null;
+    }
     const uncompressed = new Uint8Array(SWF_PREFIX_LENGTH + bodyLength);
     uncompressed.set(source.subarray(0, SWF_PREFIX_LENGTH));
     uncompressed[0] = FWS_SIGNATURE;
@@ -229,7 +262,7 @@ function populateSwfTimelineNode(clip, timeline, parsed, slots, state, depth) {
     const clips = new Map();
     for (const frame of timeline.frames) {
         const ordered = [...frame.values()].sort(compareSwfPlacementDepth);
-        frames.push(buildSwfFrameEntries(ordered, parsed, clips));
+        frames.push(buildSwfFrameEntries(ordered, parsed, clips, state.diagnostics));
         for (const placement of ordered) {
             const key = createSwfInstanceKey(placement);
             if (nodes.has(key))
@@ -268,7 +301,7 @@ function populateSwfTimelineNode(clip, timeline, parsed, slots, state, depth) {
             const target = scale9 !== null
                 ? scale9
                 : editText !== undefined
-                    ? createSwfEditTextTarget(editText, parsed, targetBounds)
+                    ? createSwfEditTextTarget(editText, parsed, targetBounds, state.diagnostics)
                     : image !== undefined
                         ? createSwfTexturedSprite(acquireSwfImageTexture(parsed, placement.characterId, false, true), targetBounds)
                         : video !== undefined
@@ -291,7 +324,7 @@ function populateSwfTimelineNode(clip, timeline, parsed, slots, state, depth) {
             }
         }
     }
-    collectSwfNodeAppearances(frames, nodes, state.appearances);
+    collectSwfNodeAppearances(frames, nodes, state.appearances, state.diagnostics);
     setMovieClipSource(clip, createSwfTimelineSource(frames, nodes, timeline.labels, timeline.cues, state.frameRate));
     // Frame scripts attach after the source, so the clip already knows how many frames it has when a
     // recognized command addresses one.
@@ -307,15 +340,24 @@ function populateSwfTimelineNode(clip, timeline, parsed, slots, state, depth) {
 //
 // One entry per (instance, frame) that carries either, so a filter that changes across frames reads as
 // the per-frame data it is. Frames are 1-based, matching gotoAndStopMovieClip.
-function collectSwfNodeAppearances(frames, nodes, out) {
+function collectSwfNodeAppearances(frames, nodes, out, diagnostics) {
     for (let frame = 0; frame < frames.length; frame++) {
         for (const entry of frames[frame]) {
             const { advancedBlendMode, effects } = entry.placement;
             if (advancedBlendMode === null && effects.length === 0)
                 continue;
             const node = nodes.get(createSwfInstanceKey(entry.placement));
-            if (node === undefined)
+            if (node === undefined) {
+                // The appearance report is the only carrier for these two channels, so a placement whose node was
+                // never allocated loses them outright. Reaching here means the placement declared one or both,
+                // which is why the earlier `continue` is not a loss and this one is. A masking placement cannot
+                // reach here despite also earning no node: masks are excluded from frame entries upstream.
+                reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Drop, 'swf.appearance-without-node', 'collectSwfNodeAppearances', {
+                    capability: advancedBlendMode !== null ? 'swf.placement.blend-mode' : 'swf.placement.filter-list',
+                    frame: frame + 1,
+                });
                 continue;
+            }
             out.push({ advancedBlendMode, effects: [...effects], frame: frame + 1, node });
         }
     }
@@ -424,28 +466,51 @@ function createSwfTimelineSource(frames, nodes, labels, cues, frameRate) {
 // placement with a clip depth covers every depth above its own through that clip depth — while Flight
 // clips a node and its subtree. Applying one region to each covered sibling is equivalent to grouping
 // them under a clipped container, and it leaves the attach/detach/reorder path untouched.
-function buildSwfFrameEntries(ordered, parsed, clips) {
+function buildSwfFrameEntries(ordered, parsed, clips, diagnostics) {
     const entries = [];
     for (const placement of ordered) {
         if (placement.clipDepth > 0)
             continue;
-        const mask = resolveSwfPlacementMask(ordered, placement);
-        entries.push({ clip: mask === null ? null : resolveSwfMaskClip(mask, placement, parsed, clips), placement });
+        const mask = resolveSwfPlacementMask(ordered, placement, diagnostics);
+        const clip = mask === null ? null : resolveSwfMaskClip(mask, placement, parsed, clips);
+        // A mask that resolves to no region leaves its covered instance UNCLIPPED, which is a visible
+        // difference and not a no-op: the mask character had no decoded geometry, so imposing nothing was
+        // the honest choice over imposing a wrong clip. Recover rather than Drop — the instance still draws.
+        if (mask !== null && clip === null) {
+            reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Recover, 'swf.mask-without-geometry', 'buildSwfFrameEntries', {
+                capability: 'swf.placement.clip-depth',
+                depth: placement.depth,
+                maskCharacterId: mask.characterId,
+            });
+        }
+        entries.push({ clip, placement });
     }
     return entries;
 }
 // The innermost mask covering a depth. Flight carries one clip per node, so where masks nest, the
 // deepest one wins rather than intersecting them.
-function resolveSwfPlacementMask(ordered, placement) {
+function resolveSwfPlacementMask(ordered, placement, diagnostics) {
     let mask = null;
+    let covering = 0;
     for (const candidate of ordered) {
         if (candidate.clipDepth <= 0 || candidate.depth >= placement.depth)
             continue;
         if (placement.depth > candidate.clipDepth)
             continue;
+        covering++;
         if (mask === null || candidate.depth > mask.depth)
             mask = candidate;
     }
+    // Two masks over one instance means the outer one is not applied at all, so the instance shows more
+    // than the file said it should. Skip rather than Recover: a node carries one clip, so this is a
+    // vocabulary gap in the clip subject rather than geometry this decoder failed to read.
+    if (covering > 1) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Skip, 'swf.nested-mask-collapsed', 'resolveSwfPlacementMask', {
+            capability: 'swf.placement.clip-depth',
+            covering,
+            depth: placement.depth,
+        });
+    }
     return mask;
 }
 function resolveSwfMaskClip(mask, placement, parsed, clips) {
@@ -581,18 +646,40 @@ function createSwfAudioResources(parsed) {
     return resources;
 }
 function createSwfImageResources(parsed) {
+    const references = new Map();
     const resources = [];
     for (const [characterId, variants] of parsed.imageTextures) {
         const image = parsed.images.get(characterId);
-        // A lossless payload already resolved at import through swfBitmap, so a reference for it would report
-        // work that does not exist and would fail if anything tried to decode it as an image file.
-        if (image === undefined || isSwfLosslessImage(image))
+        if (image === undefined)
             continue;
-        const reference = createEmbeddedImageResourceReference(image.bytes, image.mimeType);
+        const alphaType = image.mimeType === SWF_LOSSLESS_ALPHA_MIME_TYPE
+            ? 'premultiplied'
+            : image.mimeType === SWF_LOSSLESS_MIME_TYPE
+                ? 'opaque'
+                : 'straight';
+        const reference = createEmbeddedImageResourceReference(image.bytes, image.mimeType, alphaType);
         reference.textures = [...variants.values()];
+        references.set(characterId, reference);
         resources.push(reference);
     }
-    return resources;
+    return { references, resources };
+}
+// Completes the full-import sidecar after document references exist. An unplaced definition still earns
+// a report record and its own zero-texture reference; a placed one reuses the document's exact object.
+function createSwfJpegAlphaPayloads(parsed, references) {
+    const payloads = [];
+    for (const [characterId, source] of parsed.jpegAlphaPayloads) {
+        let reference = references.get(characterId);
+        if (reference === undefined) {
+            const image = parsed.images.get(characterId);
+            if (image === undefined)
+                continue;
+            reference = createEmbeddedImageResourceReference(image.bytes, image.mimeType);
+            references.set(characterId, reference);
+        }
+        payloads.push({ ...source, reference });
+    }
+    return payloads;
 }
 function createSwfTexturedSprite(texture, bounds) {
     const target = createSprite();
@@ -624,8 +711,21 @@ function createSwfMovieClip(bounds) {
 // A field becomes its own node per placement, because its text is per-instance state rather than shared
 // artwork. The authored RECT still sizes it, so a field reports the box the tool drew even before any
 // layout has run.
-function createSwfEditTextTarget(create, parsed, bounds) {
-    const node = create((fontId) => parsed.fontNames.get(fontId) ?? '');
+function createSwfEditTextTarget(create, parsed, bounds, diagnostics) {
+    // The field survives with its size, box and colour and simply has no font family, which is the
+    // diminished case: it exists, it is smaller than authored, and nothing else says so. Reported once per
+    // unresolved id rather than per call, since the resolver runs for every run of text.
+    const unresolved = new Set();
+    const node = create((fontId) => {
+        const name = parsed.fontNames.get(fontId);
+        if (name !== undefined)
+            return name;
+        if (!unresolved.has(fontId)) {
+            unresolved.add(fontId);
+            reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Drop, 'swf.edit-text-font-name-unresolved', 'createSwfEditTextTarget', { capability: 'swf.text.define-edit-text', fontId });
+        }
+        return '';
+    });
     if (bounds !== null) {
         node.data.authoredBounds = { ...bounds };
         getNodeRuntime(node).computeLocalBoundsRectangle = computeSwfLocalBoundsRectangle;
@@ -726,7 +826,7 @@ function createSwfSymbolNode(parsed, characterId, slots, state) {
     const bounds = resolveSwfCharacterBounds(parsed, characterId, state, 0);
     const editText = parsed.editTexts.get(characterId);
     if (editText !== undefined)
-        return createSwfEditTextTarget(editText, parsed, bounds);
+        return createSwfEditTextTarget(editText, parsed, bounds, state.diagnostics);
     if (parsed.images.has(characterId)) {
         return createSwfTexturedSprite(acquireSwfImageTexture(parsed, characterId, false, true), bounds);
     }
@@ -759,16 +859,29 @@ function resolveSwfCharacterBounds(parsed, characterId, state, depth) {
     // A symbol's authored extent covers everything it can show, so this unions every frame's placements
     // rather than only the first frame's: the node's local bounds do not change as its playhead moves.
     let bounds = null;
+    let missingChildren = 0;
     for (const frame of sprite.frames) {
         for (const placement of frame.values()) {
             const childBounds = resolveSwfCharacterBounds(parsed, placement.characterId, state, depth + 1);
-            if (childBounds === null)
+            if (childBounds === null) {
+                // Two different things reach here and only one is a loss. A sprite that resolved to an empty
+                // union has no extent to contribute and is correct; a character with neither authored bounds nor
+                // a sprite body was never imported at all, and the union it should have widened is short.
+                if (!parsed.characterBounds.has(placement.characterId) && !parsed.sprites.has(placement.characterId)) {
+                    missingChildren++;
+                }
                 continue;
+            }
             const transformed = transformSwfRectangle(childBounds, placement.matrix);
             bounds = bounds === null ? transformed : mergeSwfRectangles(bounds, transformed);
         }
     }
     state.resolvingBounds.delete(characterId);
+    if (missingChildren > 0) {
+        // A count rather than a flag: the box survives and is simply smaller than the sprite's contents, and
+        // a count is the only thing that separates a full union from a short one.
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.sprite-bounds-short', 'resolveSwfCharacterBounds', { capability: 'swf.timeline.define-sprite', characterId, missingChildren });
+    }
     state.resolvedBounds.set(characterId, bounds);
     return bounds;
 }
@@ -787,7 +900,7 @@ function transformSwfRectangle(bounds, matrix) {
     const maxY = Math.max(y0, y1, y2, y3);
     return { height: maxY - y, width: maxX - x, x, y };
 }
-function readPlaceObject(body, placements, hasExtendedFlags) {
+function readPlaceObject(body, placements, hasExtendedFlags, diagnostics) {
     const flags = body.readUint8();
     const extendedFlags = hasExtendedFlags ? body.readUint8() : 0;
     const depth = body.readUint16();
@@ -811,8 +924,15 @@ function readPlaceObject(body, placements, hasExtendedFlags) {
     const hasFilterList = (extendedFlags & 0x01) !== 0;
     const readEffects = [];
     const readFilterAdjustments = [];
-    const filterListComplete = !hasFilterList || readSwfFilterList(body, readEffects, readFilterAdjustments);
-    const hasBlendMode = (extendedFlags & 0x02) !== 0 && filterListComplete;
+    const filterListComplete = !hasFilterList || readSwfFilterList(body, readEffects, readFilterAdjustments, diagnostics);
+    const declaresBlendMode = (extendedFlags & 0x02) !== 0;
+    const hasBlendMode = declaresBlendMode && filterListComplete;
+    if (declaresBlendMode && !filterListComplete) {
+        // The record declared a blend mode and the byte carrying it is unreachable behind a list that did
+        // not finish. The placement keeps the filters read so far, so nothing about the result says a
+        // declared channel went unread.
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Drop, 'swf.blend-mode-behind-unread-filters', 'readPlaceObject', { capability: 'swf.placement.blend-mode' });
+    }
     const blendModeValue = hasBlendMode ? body.readUint8() : 0;
     if (!body.valid || (isMove && existing === undefined) || (characterId === 0 && directLinkage === null))
         return;
@@ -1006,10 +1126,11 @@ function readSwfRectangle(reader) {
         y: yMin / TWIPS_PER_PIXEL,
     };
 }
-function readSwfTags(reader) {
+function readSwfTags(reader, diagnostics) {
     const state = {
         abcBlobs: [],
         backgroundColor: null,
+        diagnostics,
         pendingInitActions: [],
         editTexts: new Map(),
         fontNames: new Map(),
@@ -1019,6 +1140,7 @@ function readSwfTags(reader) {
         fontOutlineSources: new Map(),
         images: new Map(),
         imageTextures: new Map(),
+        jpegAlphaPayloads: new Map(),
         jpegTables: null,
         pendingTexts: [],
         linkages: new Map(),
@@ -1057,6 +1179,7 @@ function readSwfTags(reader) {
         fontOutlineSources: state.fontOutlineSources,
         images: state.images,
         imageTextures: state.imageTextures,
+        jpegAlphaPayloads: state.jpegAlphaPayloads,
         linkages: state.linkages,
         morphBounds: state.morphBounds,
         morphShapes: state.morphShapes,
@@ -1098,9 +1221,11 @@ function appendSwfAbcFrameScripts(state, timeline) {
     for (const [characterId, className] of state.linkages)
         charactersByClass.set(className, characterId);
     for (const blob of state.abcBlobs) {
-        const byClass = readSwfAbcFrameScripts(blob);
-        if (byClass === null)
+        const byClass = readSwfAbcFrameScripts(blob.bytes, state.diagnostics);
+        if (byClass === null) {
+            reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.abc-frame-scripts-unreadable', 'appendSwfAbcFrameScripts', { capability: blob.named ? 'swf.script.do-abc' : 'swf.script.do-abc-anonymous' });
             continue;
+        }
         for (const [className, frames] of byClass) {
             const characterId = charactersByClass.get(className);
             if (characterId === undefined)
@@ -1116,8 +1241,17 @@ function appendSwfAbcFrameScripts(state, timeline) {
 function appendSwfPendingTextShapes(reader, state) {
     for (const pending of state.pendingTexts) {
         const shape = createSwfTextShape(new SwfReader(reader.source, pending.start, pending.end), pending.version, state.fontOutlineSources);
-        if (shape !== null)
-            state.shapes.set(pending.characterId, shape);
+        if (shape === null) {
+            // Composition is deferred because the records address glyphs by index into a font that may not
+            // have been read yet, so the failure lands here rather than at the tag. Without a report the
+            // character is simply absent and every placement of it resolves to nothing.
+            reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.text-shape-uncomposable', 'appendSwfPendingTextShapes', {
+                capability: pending.version === 2 ? 'swf.text.define-text-2' : 'swf.text.define-text',
+                characterId: pending.characterId,
+            });
+            continue;
+        }
+        state.shapes.set(pending.characterId, shape);
     }
 }
 function readSwfTimeline(reader, state) {
@@ -1148,27 +1282,43 @@ function readSwfTimeline(reader, state) {
             frames.push(new Map(placements));
         }
         else if (code === TAG_DO_ABC || code === TAG_DO_ABC_ANONYMOUS) {
-            state.abcBlobs.push(readSwfAbcPayload(body, code === TAG_DO_ABC));
+            state.abcBlobs.push({ bytes: readSwfAbcPayload(body, code === TAG_DO_ABC), named: code === TAG_DO_ABC });
         }
         else if (code === TAG_DO_INIT_ACTION) {
             // An init action runs once for the sprite it names, before that sprite's own first frame, so a
             // recognized block belongs to frame 1 of that sprite rather than to the timeline reading the tag.
             const spriteId = body.readUint16();
             const script = readSwfFrameActions(new SwfReader(body.source, body.pos, body.end));
-            if (script !== null)
+            if (script === null) {
+                // Same decline as DoAction below and the same Skip reasoning: the bytecode is outside this
+                // importer's scope by charter rather than data it failed to read. It reports the sprite it names
+                // rather than a frame, because an init action runs before that sprite's first frame.
+                reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Skip, 'swf.frame-script-declined', 'readSwfTimeline', { capability: 'swf.script.do-init-action', characterId: spriteId });
+            }
+            else {
                 state.pendingInitActions.push({ characterId: spriteId, script });
+            }
         }
         else if (code === TAG_DO_ACTION) {
             // A DoAction belongs to the frame being assembled — the one the next ShowFrame closes.
             const script = readSwfFrameActions(new SwfReader(body.source, body.pos, body.end));
             if (script !== null)
                 actions.set(frames.length + 1, script);
+            // A block is recognized only when EVERY action in it is a playback command, because honouring the
+            // legible half would misrepresent what the frame does. Skip rather than Drop: the bytecode is
+            // outside this importer's scope by charter, not data it failed to read.
+            else {
+                reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Skip, 'swf.frame-script-declined', 'readSwfTimeline', {
+                    capability: 'swf.script.do-action',
+                    frame: frames.length + 1,
+                });
+            }
         }
         else if (code === TAG_FRAME_LABEL) {
             addSwfTimelineLabel(labels, frames.length + 1, body.readString());
         }
         else if (code === TAG_DEFINE_SCENE_AND_FRAME_LABEL_DATA) {
-            readSwfSceneAndFrameLabelData(body, labels);
+            readSwfSceneAndFrameLabelData(body, labels, state.diagnostics);
         }
         else if (code === TAG_DEFINE_SCALING_GRID) {
             readSwfScalingGrid(body, state);
@@ -1177,7 +1327,7 @@ function readSwfTimeline(reader, state) {
             readLegacyPlaceObject(body, placements);
         }
         else if (code === TAG_PLACE_OBJECT_2) {
-            readPlaceObject(body, placements, false);
+            readPlaceObject(body, placements, false, state.diagnostics);
         }
         else if (code === TAG_REMOVE_OBJECT) {
             readLegacyRemoveObject(body, placements);
@@ -1238,7 +1388,7 @@ function readSwfTimeline(reader, state) {
             state.sprites.set(spriteId, spriteTimeline);
         }
         else if (code === TAG_PLACE_OBJECT_3 || code === TAG_PLACE_OBJECT_4) {
-            readPlaceObject(body, placements, true);
+            readPlaceObject(body, placements, true, state.diagnostics);
         }
         else if (code === TAG_START_SOUND) {
             readSwfStartSound(body, state, cues, frames.length + 1);
@@ -1263,6 +1413,15 @@ function readSwfTimeline(reader, state) {
                 if (body.valid && body.pos < body.end)
                     streamChunks.push(body.source.subarray(body.pos, body.end));
             }
+            else if (streamFormat >= 0) {
+                reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Skip, 'swf.stream-sound-format', 'readSwfTimeline', {
+                    capability: 'swf.axis.sound-format-non-mp3',
+                    format: streamFormat,
+                });
+            }
+        }
+        else {
+            reportSwfDeclinedTag(state.diagnostics, code);
         }
         if (!body.valid)
             return null;
@@ -1273,15 +1432,46 @@ function readSwfTimeline(reader, state) {
     if (frames.length === 0)
         frames.push(placements);
     appendSwfStreamSoundCue(state, cues, streamChunks, streamStartFrame);
+    // A label or cue authored after the last ShowFrame names a frame the timeline never reaches, so it is
+    // dropped rather than bound to a frame that does not exist. Found by auditing the claim rather than the
+    // wire: `swf.scene-names` covered only the scene table, while THIS is the other way that tag's data is
+    // lost, and silence about it was being reported as trustworthy.
+    const reachableCues = cues.filter((cue) => cue.frame <= frames.length);
+    const reachableLabels = labels.filter((label) => label.frame <= frames.length);
+    if (reachableLabels.length !== labels.length) {
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.label-past-last-frame', 'readSwfTimeline', {
+            capability: 'swf.timeline.frame-label',
+            dropped: labels.length - reachableLabels.length,
+            frames: frames.length,
+        });
+    }
+    if (reachableCues.length !== cues.length) {
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.cue-past-last-frame', 'readSwfTimeline', {
+            dropped: cues.length - reachableCues.length,
+            frames: frames.length,
+        });
+    }
     return {
         actions,
-        // A cue authored after the last ShowFrame names a frame the timeline never reaches.
-        cues: cues.filter((cue) => cue.frame <= frames.length),
+        cues: reachableCues,
         frames,
-        // A label declared after the last ShowFrame names a frame the timeline never reaches.
-        labels: labels.filter((label) => label.frame <= frames.length).sort(compareSwfTimelineLabelFrame),
+        labels: reachableLabels.sort(compareSwfTimelineLabelFrame),
     };
 }
+// Reports the tags this importer deliberately reads past that cost a real capability, and stays silent on
+// the ones that cost nothing. The line matters: a document is not worse off for having skipped
+// `FileAttributes` or a font's hinting table, so reporting those would bury the entries that do mean
+// something under noise a caller has to filter. Every code below is a decision recorded in
+// `agents/packages/swf/tag-coverage.md`, not an unrecognized tag.
+function reportSwfDeclinedTag(diagnostics, code) {
+    if (diagnostics === undefined)
+        return;
+    const kind = SWF_DECLINED_TAG_KINDS.get(code);
+    if (kind === undefined)
+        return;
+    const capability = SWF_DECLINED_TAG_CAPABILITIES.get(code);
+    reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Skip, kind, 'readSwfTimeline', capability === undefined ? { tag: code } : { capability, tag: code });
+}
 // The stage colour, as an RGB record. SWF gives it no alpha, and a stage is opaque, so it packs to fully
 // opaque RGBA. Last declaration wins, matching how a player applies the most recent one it has read.
 // A button is a display character whose content is a small display list per interaction state. A document
@@ -1312,6 +1502,14 @@ function readSwfButtonDefinition(body, state, version) {
         const colorTransform = version === 2 ? readSwfColorTransform(reader) : null;
         if (!reader.valid)
             return;
+        if ((flags & BUTTON_STATE_UP) === 0 && characterId !== 0) {
+            // A document is a still scene, so only the up state is held. The other states are a real capability
+            // gap rather than data this decoder could not read, which is why they Skip rather than Drop.
+            reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Skip, 'swf.button-interaction-state', 'readSwfButtonDefinition', {
+                characterId,
+                flags,
+            });
+        }
         if ((flags & BUTTON_STATE_UP) !== 0 && characterId !== 0) {
             placements.set(depth, {
                 advancedBlendMode: null,
@@ -1348,9 +1546,28 @@ function readSwfFontDefinition(body, state, code) {
     const version = code === TAG_DEFINE_FONT ? 1 : code === TAG_DEFINE_FONT_2 ? 2 : 3;
     const reader = new SwfReader(body.source, body.pos, body.end);
     const fontId = reader.source[body.pos] + reader.source[body.pos + 1] * 0x100;
-    const source = readSwfFontGlyphOutlineSource(reader, version);
-    if (source === null || fontId === 0)
+    const source = readSwfFontGlyphOutlineSource(reader, version, state.diagnostics, fontId);
+    // A glyph table this decoder cannot read at all costs the WHOLE font, not one glyph, so it is a
+    // separate loss from `swf.font-glyph-outline` and must report separately: without this, a font that
+    // vanished entirely and a font that imported cleanly both produce no crumb.
+    if (source === null) {
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.font-glyph-table', 'readSwfFontDefinition', {
+            capability: version === 1 ? 'swf.font.define-font' : `swf.font.define-font-${version}`,
+            characterId: fontId,
+        });
         return;
+    }
+    if (fontId === 0)
+        return;
+    if (state.fontOutlineSources.has(fontId)) {
+        // Every other definition kind rejects the document on a repeated character id; fonts do not, so the
+        // second table silently replaces the first. The document imports, the font exists, and it is the
+        // wrong font — no existence check and no count can see that, which is why it is reported here.
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.font-character-id-reused', 'readSwfFontDefinition', {
+            capability: version === 1 ? 'swf.font.define-font' : `swf.font.define-font-${version}`,
+            characterId: fontId,
+        });
+    }
     state.fontOutlineSources.set(fontId, source);
     const fontName = readSwfFontName(body, version);
     if (fontName !== '')
@@ -1438,12 +1655,21 @@ function readSwfScalingGrid(body, state) {
         return;
     state.scalingGrids.set(characterId, splitter);
 }
-function readSwfSceneAndFrameLabelData(body, labels) {
+function readSwfSceneAndFrameLabelData(body, labels, diagnostics) {
     const sceneCount = body.readEncodedUint32();
     for (let i = 0; i < sceneCount && body.valid; i++) {
         body.readEncodedUint32();
         body.readString();
     }
+    // Scene names are read past to reach the label table behind them. Skip rather than Drop: Flight has
+    // frame labels but no subject for a named frame range, so this is a capability gap rather than data
+    // this decoder failed to read.
+    if (sceneCount > 0) {
+        reportImportDiagnostic(diagnostics, ImportDiagnosticSeverity.Skip, 'swf.scene-names', 'readSwfSceneAndFrameLabelData', {
+            capability: 'swf.timeline.define-scene-and-frame-label-data',
+            sceneCount,
+        });
+    }
     const labelCount = body.readEncodedUint32();
     for (let i = 0; i < labelCount && body.valid; i++) {
         const frame = body.readEncodedUint32();
@@ -1494,8 +1720,12 @@ function readSwfBoundedDefinition(body, state, code) {
         const reader = new SwfReader(body.source, body.pos, body.end);
         const bounds = state.characterBounds.get(characterId);
         const factory = readSwfEditTextFactory(reader, bounds?.width ?? 0, bounds?.height ?? 0);
-        if (factory !== null)
+        if (factory === null) {
+            reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.edit-text-unparseable', 'readSwfBoundedDefinition', { capability: 'swf.text.define-edit-text', characterId });
+        }
+        else {
             state.editTexts.set(characterId, factory);
+        }
     }
     if (code === TAG_DEFINE_TEXT || code === TAG_DEFINE_TEXT_2) {
         const reader = new SwfReader(body.source, body.pos, body.end);
@@ -1525,9 +1755,18 @@ function readSwfShapeBody(body, state, characterId, version) {
         return;
     // The fill's character is not this shape's, hence the distinct name: a bitmap fill names whatever
     // character carries its pixels, which may be defined later in the tag stream.
-    const shape = createSwfShape(reader, version, (fillCharacterId, repeat, smoothed) => acquireSwfImageTexture(state, fillCharacterId, repeat, smoothed));
-    if (shape !== null)
-        state.shapes.set(characterId, shape);
+    const shape = createSwfShape(reader, version, (fillCharacterId, repeat, smoothed) => acquireSwfImageTexture(state, fillCharacterId, repeat, smoothed), state.diagnostics);
+    if (shape === null) {
+        // Recover rather than Drop: the character survives as the bounded placeholder it was before any
+        // geometry existed, so the document still places and sizes it — only the drawing is missing.
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Recover, 'swf.shape-body-unreadable', 'readSwfShapeDefinition', {
+            capability: version === 1 ? 'swf.shape.define-shape' : `swf.shape.define-shape-${version}`,
+            characterId,
+            version,
+        });
+        return;
+    }
+    state.shapes.set(characterId, shape);
 }
 // Decodes a morph definition's geometry and paint on a reader of its own, so a body this decoder cannot
 // read costs only that body. The definition keeps its authored bounds and contributes no drawing, which
@@ -1539,9 +1778,17 @@ function readSwfMorphShapeBody(body, state, characterId, version) {
     const source = body.source;
     const start = body.pos;
     const end = body.end;
-    const decode = () => createSwfMorphShape(new SwfReader(source, start, end), version, (fillCharacterId, repeat, smoothed) => acquireSwfImageTexture(state, fillCharacterId, repeat, smoothed));
-    if (decode() !== null)
-        state.morphShapes.set(characterId, decode);
+    // Only the parse-time validation call carries the sink. The stored closure runs again per placement,
+    // potentially long after import returned, and a sink written to then would append to a collection
+    // whose consumer has already read it.
+    const decode = (diagnostics) => createSwfMorphShape(new SwfReader(source, start, end), version, (fillCharacterId, repeat, smoothed) => acquireSwfImageTexture(state, fillCharacterId, repeat, smoothed), diagnostics);
+    if (decode(state.diagnostics) === null) {
+        // The character is simply absent from the document afterwards, so without this the loss has no
+        // signal at all: a placement of it resolves to nothing and the import still reports success.
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.morph-shape-undecodable', 'readSwfMorphShapeBody', { capability: version === 2 ? 'swf.morph.define-morph-shape-2' : 'swf.morph.define-morph-shape', characterId });
+        return;
+    }
+    state.morphShapes.set(characterId, decode);
 }
 function resolveSwfMorphShapeVersion(code) {
     if (code === TAG_DEFINE_MORPH_SHAPE)
@@ -1569,8 +1816,13 @@ function readSwfLegacyImageDefinition(body, state) {
     if (!body.valid || characterId === 0 || state.definedCharacters.has(characterId))
         return;
     const tables = state.jpegTables;
-    if (tables === null)
+    if (tables === null) {
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.jpeg-tables-missing', 'readSwfLegacyImageDefinition', {
+            capability: 'swf.bitmap.define-bits-jpeg-tables',
+            characterId,
+        });
         return;
+    }
     const tablesEnd = tables.length >= 2 && tables[tables.length - 2] === 0xff && tables[tables.length - 1] === JPEG_END_OF_IMAGE
         ? tables.length - 2
         : tables.length;
@@ -1579,8 +1831,13 @@ function readSwfLegacyImageDefinition(body, state) {
     spliced.set(tables.subarray(0, tablesEnd));
     spliced.set(body.source.subarray(imageStart, body.end), tablesEnd);
     const image = readSwfEmbeddedImage(spliced, 0, spliced.length);
-    if (image === null)
+    if (image === null) {
+        reportImportDiagnostic(state.diagnostics, ImportDiagnosticSeverity.Drop, 'swf.jpeg-tables-unsplittable', 'readSwfLegacyImageDefinition', {
+            capability: 'swf.bitmap.define-bits-jpeg-tables',
+            characterId,
+        });
         return;
+    }
     state.definedCharacters.add(characterId);
     state.characterBounds.set(characterId, image.bounds);
     state.images.set(characterId, { bytes: spliced, mimeType: image.mimeType });
@@ -1590,13 +1847,16 @@ function readSwfLegacyImageDefinition(body, state) {
 // costs far more than the picture is worth.
 function readSwfEmbeddedImageDefinition(body, state, code) {
     const characterId = body.readUint16();
+    let deblockingParameterRaw = null;
     let imageStart = body.pos;
     let imageEnd = body.end;
+    let hasAlphaPayload = false;
     if (code === TAG_DEFINE_BITS_JPEG_3 || code === TAG_DEFINE_BITS_JPEG_4) {
+        hasAlphaPayload = true;
         const alphaDataOffset = body.readUint32();
         const alphaOffsetBase = body.pos;
         if (code === TAG_DEFINE_BITS_JPEG_4)
-            body.readUint16();
+            deblockingParameterRaw = body.readUint16();
         imageStart = body.pos;
         imageEnd = alphaOffsetBase + alphaDataOffset;
     }
@@ -1616,6 +1876,28 @@ function readSwfEmbeddedImageDefinition(body, state, code) {
         bytes: stripSwfJpegStreamBoundary(body.source, imageStart, imageEnd, image.mimeType),
         mimeType: image.mimeType,
     });
+    if (hasAlphaPayload) {
+        const compressedAlphaBytes = body.source.subarray(imageEnd, body.end);
+        state.jpegAlphaPayloads.set(characterId, {
+            characterId,
+            compressedAlphaBytes,
+            deblockingParameterRaw,
+            height: image.bounds.height,
+            width: image.bounds.width,
+        });
+        // The full report retains this stream, but the document's colour reference still resolves without
+        // applying it. Keep the existing fidelity diagnostic until the separately-gated composition stage.
+        if (compressedAlphaBytes.length > 0) {
+            reportImportDiagnostic(state.diagnostics, 
+            // Skip: the alpha stream is recognized and deliberately not applied until the composition stage
+            // exists. A capability gap on a well-formed file, with no substitute written.
+            ImportDiagnosticSeverity.Skip, 'swf.jpeg-alpha-stream', 'readSwfEmbeddedImageDefinition', {
+                capability: code === TAG_DEFINE_BITS_JPEG_3 ? 'swf.bitmap.define-bits-jpeg-3' : 'swf.bitmap.define-bits-jpeg-4',
+                characterId,
+                discardedBytes: compressedAlphaBytes.length,
+            });
+        }
+    }
     return;
 }
 // Identifies an embedded payload by its magic bytes and reads the dimensions out of its header, without
@@ -2030,8 +2312,6 @@ const S_SIGNATURE = 0x53;
 const MORPH_RATIO_ONE = 0xffff;
 const SWF_INSTANCE_KEY_SCALE = 0x10000;
 const SWF_LZMA_PREFIX_LENGTH = 17;
-const SWF_LOSSLESS_ALPHA_MIME_TYPE = 'image/x-swf-lossless-alpha';
-const SWF_LOSSLESS_MIME_TYPE = 'image/x-swf-lossless';
 const SWF_MIME_TYPE = 'application/x-shockwave-flash';
 const SWF_PREFIX_LENGTH = 8;
 const SOUND_ENVELOPE_LEVEL_ONE = 32768;
@@ -2065,6 +2345,22 @@ const TAG_START_SOUND_2 = 89;
 const TAG_SOUND_STREAM_BLOCK = 19;
 const TAG_SOUND_STREAM_HEAD = 18;
 const TAG_SOUND_STREAM_HEAD_2 = 45;
+// Only tags whose absence loses something a caller could want. Metadata tags — `FileAttributes`,
+// `Metadata`, `ProductInfo`, `ScriptLimits`, `DebugID`, `EnableDebugger2`, `EnableTelemetry`, `Protect`,
+// `SetTabIndex`, `DefineButtonCxform`, and the font hinting/naming tables — are deliberately absent: they
+// carry no scene content, so skipping one is not a loss to report.
+// The declared capability a declined tag costs, where one exists. Deliberately partial: `DefineFont4`,
+// `DefineBinaryData`, `ImportAssets` and `DefineButtonSound` name no declared capability, and inventing
+// one so every crumb could carry a join key would put entries in the denominator that nothing measures.
+const SWF_DECLINED_TAG_CAPABILITIES = new Map([[61, 'swf.video.video-frame']]);
+const SWF_DECLINED_TAG_KINDS = new Map([
+    [17, 'swf.define-button-sound'],
+    [57, 'swf.import-assets'],
+    [61, 'swf.video-frame-payload'],
+    [71, 'swf.import-assets'],
+    [87, 'swf.define-binary-data'],
+    [91, 'swf.define-font-4'],
+]);
 const TAG_DEFINE_SCALING_GRID = 78;
 const TAG_DEFINE_SCENE_AND_FRAME_LABEL_DATA = 86;
 const TAG_DEFINE_BITS_JPEG_2 = 21;