swf-toolkit 0.0.0-stage → 0.1.0

package/dist/cjs/project/pcode-project.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANIFEST_NAME = void 0;
+exports.safeSegment = safeSegment;
+exports.exportPcode = exportPcode;
+exports.splitMethodBlocks = splitMethodBlocks;
+exports.importPcode = importPcode;
+/**
+ * Export every class of an SWF to editable `.pcode` files and import the
+ * edited files back. Only methods whose text actually changed are
+ * re-assembled, so untouched code stays byte-identical.
+ */
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const abc_file_js_1 = require("../abc/abc-file.js");
+const interner_js_1 = require("../abc/interner.js");
+const model_js_1 = require("../abc/model.js");
+const assembler_js_1 = require("../abc/pcode/assembler.js");
+const disassembler_js_1 = require("../abc/pcode/disassembler.js");
+const format_js_1 = require("../abc/pcode/format.js");
+const lexer_js_1 = require("../abc/pcode/lexer.js");
+const errors_js_1 = require("../errors.js");
+exports.MANIFEST_NAME = 'swf-toolkit.json';
+/** Make a class / package name safe as a path segment on all platforms. */
+function safeSegment(s) {
+    if (s === '' || s === '.' || s === '..')
+        return `_${s.length}_`;
+    let out = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (/[\\/:*?"<>|%]/.test(ch) || cp < 0x20 || cp === 0x7f || (cp >= 0xd800 && cp <= 0xdfff))
+            out += `%${cp.toString(16).padStart(2, '0')}`;
+        else
+            out += ch;
+    }
+    if (/^(con|prn|aux|nul|com\d|lpt\d)$/i.test(out))
+        out = `%${out}`;
+    if (/[. ]$/.test(out))
+        out += '%';
+    return out.length > 180 ? out.slice(0, 160) + '%' + hash(s) : out;
+}
+function hash(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++)
+        h = Math.imul(h ^ s.charCodeAt(i), 16777619);
+    return (h >>> 0).toString(16);
+}
+function classFilePath(className) {
+    const { pkg, name } = (0, abc_file_js_1.splitQualifiedName)(className);
+    const parts = pkg ? pkg.split('.').map(safeSegment) : [];
+    return [...parts, safeSegment(name) + '.pcode'].join('/');
+}
+function renderFile(abc, header, owner, refs, done) {
+    const chunks = [header.map((h) => `; ${h}`).join('\n') + '\n'];
+    const methods = [];
+    for (const r of refs) {
+        if (done.has(r.methodIndex) || !abc.methods[r.methodIndex])
+            continue;
+        done.add(r.methodIndex);
+        methods.push(r.methodIndex);
+        chunks.push((0, disassembler_js_1.disassembleMethod)(abc, r.methodIndex, { title: (0, model_js_1.describeMethodRef)(abc, owner, r) }));
+    }
+    return { text: chunks.join('\n'), methods };
+}
+/** Writes one `.pcode` file per class (plus a manifest) into `outDir`. */
+async function exportPcode(swf, outDir) {
+    const tags = swf.abcTags;
+    const manifest = { format: 'swf-toolkit-pcode', version: 1, abcs: [], files: {} };
+    const written = [];
+    let methodCount = 0;
+    for (let k = 0; k < tags.length; k++) {
+        const tag = tags[k];
+        const abc = tag.abc;
+        const base = tags.length > 1 ? `_abc${k}_${safeSegment(tag.abcName || 'unnamed')}` : '';
+        manifest.abcs.push({ name: tag.abcName, dir: base });
+        const done = new Set();
+        const used = new Set();
+        const unique = (p) => {
+            let candidate = p;
+            for (let n = 2; used.has(candidate.toLowerCase()); n++)
+                candidate = p.replace(/\.pcode$/, `~${n}.pcode`);
+            used.add(candidate.toLowerCase());
+            return candidate;
+        };
+        const emit = async (rel, text, entry) => {
+            const path = base ? `${base}/${rel}` : rel;
+            const abs = (0, node_path_1.join)(outDir, ...path.split('/'));
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(abs), { recursive: true });
+            await (0, promises_1.writeFile)(abs, text, 'utf8');
+            manifest.files[path] = entry;
+            written.push(abs);
+            methodCount += entry.methods.length;
+        };
+        const scriptDone = new Set();
+        for (let c = 0; c < abc.instances.length; c++) {
+            const name = abc.className(c);
+            const inst = abc.instances[c];
+            const header = [
+                `class ${name}  (class index ${c})`,
+                `extends ${inst.superName ? (0, format_js_1.formatMultiname)(abc, inst.superName) : '-'}`,
+                ...(inst.interfaces.length ? [`implements ${inst.interfaces.map((i) => (0, format_js_1.formatMultiname)(abc, i)).join(', ')}`] : []),
+                'Edit method blocks and run import; blocks you do not change are left untouched.',
+            ];
+            const refs = [];
+            const s = (0, model_js_1.scriptOfClass)(abc, c);
+            if (s >= 0 && !scriptDone.has(s)) {
+                scriptDone.add(s);
+                refs.push(...(0, model_js_1.scriptMethods)(abc, s, false));
+            }
+            refs.push(...(0, model_js_1.classMethods)(abc, c));
+            const { text, methods } = renderFile(abc, header, name, refs, done);
+            await emit(unique(classFilePath(name)), text, { abc: k, className: name, methods });
+        }
+        for (let s = 0; s < abc.scripts.length; s++) {
+            if (scriptDone.has(s))
+                continue;
+            const refs = (0, model_js_1.scriptMethods)(abc, s);
+            const { text, methods } = renderFile(abc, [`script ${s}`], `script${s}`, refs, done);
+            if (methods.length)
+                await emit(unique(`_scripts/script_${s}.pcode`), text, { abc: k, methods });
+        }
+        // Anything not reachable from classes or scripts.
+        const rest = [];
+        for (let m = 0; m < abc.methods.length; m++)
+            if (!done.has(m))
+                rest.push({ methodIndex: m, role: 'closure', name: abc.strings[abc.methods[m].name] ?? '', isStatic: false });
+        if (rest.length) {
+            const { text, methods } = renderFile(abc, ['methods not referenced by any class or script'], '<orphan>', rest, done);
+            await emit(unique('_scripts/orphans.pcode'), text, { abc: k, methods });
+        }
+    }
+    const manifestPath = (0, node_path_1.join)(outDir, exports.MANIFEST_NAME);
+    await (0, promises_1.mkdir)(outDir, { recursive: true });
+    await (0, promises_1.writeFile)(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    return { outDir, files: written, methodCount };
+}
+/** Splits a P-code document into `method ... end` blocks with their method index. */
+function splitMethodBlocks(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let start = -1;
+    let index = 'new';
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^\s*method\s+(\d+|new)\b/.exec(lines[i]);
+        if (m && start < 0) {
+            start = i;
+            index = m[1] === 'new' ? 'new' : Number(m[1]);
+        }
+        else if (start >= 0 && /^\s*end\s*(;.*)?$/.test(lines[i])) {
+            // Pad with blank lines so assembler line numbers match the file.
+            blocks.push({ text: '\n'.repeat(start) + lines.slice(start, i + 1).join('\n'), startLine: start + 1, methodIndex: index });
+            start = -1;
+        }
+    }
+    if (start >= 0)
+        throw new errors_js_1.AssemblerError("Missing 'end'", lines.length, 1);
+    return blocks;
+}
+/** Token-level normalisation: ignores comments, indentation and spacing. */
+function normalize(text) {
+    return text
+        .split('\n')
+        .map((l, i) => (0, lexer_js_1.tokenizeLine)(l, i + 1).map((t) => t.text).join(' '))
+        .filter((l) => l.length > 0)
+        .join('\n');
+}
+/** Applies edited `.pcode` files from `dir` (created by {@link exportPcode}) to `swf`. */
+async function importPcode(swf, dir, options = {}) {
+    const manifest = JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(dir, exports.MANIFEST_NAME), 'utf8'));
+    if (manifest.format !== 'swf-toolkit-pcode')
+        throw new Error(`${exports.MANIFEST_NAME} is not a swf-toolkit P-code manifest`);
+    const tags = swf.abcTags;
+    const interners = new Map();
+    const result = { changed: [], unchanged: 0 };
+    const only = options.files ? new Set(options.files.map((f) => f.split(node_path_1.sep).join('/'))) : undefined;
+    for (const [rel, entry] of Object.entries(manifest.files)) {
+        if (only && !only.has(rel))
+            continue;
+        const tag = tags[entry.abc];
+        if (!tag)
+            throw new Error(`${rel}: ABC tag #${entry.abc} not found in SWF`);
+        const abc = tag.abc;
+        const path = (0, node_path_1.join)(dir, ...rel.split('/'));
+        let text;
+        try {
+            text = await (0, promises_1.readFile)(path, 'utf8');
+        }
+        catch {
+            continue; // file deleted: leave methods as they are
+        }
+        for (const block of splitMethodBlocks(text)) {
+            if (block.methodIndex !== 'new') {
+                const current = abc.methods[block.methodIndex] ? (0, disassembler_js_1.disassembleMethod)(abc, block.methodIndex) : '';
+                if (normalize(current) === normalize(block.text)) {
+                    result.unchanged++;
+                    continue;
+                }
+            }
+            let interner = interners.get(entry.abc);
+            if (!interner) {
+                interner = new interner_js_1.Interner(abc);
+                interners.set(entry.abc, interner);
+            }
+            const assembled = (0, assembler_js_1.assembleMethods)(abc, block.text, { source: (0, node_path_1.relative)(process.cwd(), path), interner });
+            for (const a of assembled)
+                result.changed.push({ file: rel, methodIndex: a.methodIndex });
+        }
+    }
+    return result;
+}

package/dist/cjs/project/source-export.d.ts

@@ -0,0 +1,12 @@
+import type { Swf } from '../swf/swf.js';
+/** First-line marker identifying the exact class an exported file belongs to. */
+export declare const CLASS_MARKER = "// swf-toolkit:";
+export interface ExportSourcesResult {
+    files: string[];
+    /** Classes whose decompilation threw (a stub with the error was written). */
+    failed: string[];
+}
+/** Writes decompiled `.as` files (one per class) into `outDir`. */
+export declare function exportSources(swf: Swf, outDir: string, options?: {
+    classes?: string[];
+}): Promise<ExportSourcesResult>;

package/dist/cjs/project/source-export.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLASS_MARKER = void 0;
+exports.exportSources = exportSources;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const abc_file_js_1 = require("../abc/abc-file.js");
+const class_printer_js_1 = require("../decompiler/class-printer.js");
+const pcode_project_js_1 = require("./pcode-project.js");
+/** First-line marker identifying the exact class an exported file belongs to. */
+exports.CLASS_MARKER = '// swf-toolkit:';
+/** Writes decompiled `.as` files (one per class) into `outDir`. */
+async function exportSources(swf, outDir, options = {}) {
+    const files = [];
+    const failed = [];
+    const used = new Set();
+    const only = options.classes ? new Set(options.classes) : undefined;
+    const tags = swf.abcTags;
+    for (let k = 0; k < tags.length; k++) {
+        const abc = tags[k].abc;
+        const counts = new Map();
+        for (let c = 0; c < abc.instances.length; c++)
+            counts.set(abc.className(c), (counts.get(abc.className(c)) ?? 0) + 1);
+        for (let c = 0; c < abc.instances.length; c++) {
+            const name = abc.className(c);
+            if (only && !only.has(name))
+                continue;
+            const { pkg, name: short } = (0, abc_file_js_1.splitQualifiedName)(name);
+            let rel = [...(pkg ? pkg.split('.').map(pcode_project_js_1.safeSegment) : []), (0, pcode_project_js_1.safeSegment)(short) + '.as'].join('/');
+            for (let n = 2; used.has(rel.toLowerCase()); n++)
+                rel = rel.replace(/(~\d+)?\.as$/, `~${n}.as`);
+            used.add(rel.toLowerCase());
+            let text;
+            try {
+                text = (0, class_printer_js_1.decompileClass)(abc, c);
+            }
+            catch (e) {
+                failed.push(name);
+                text = `// Failed to decompile ${name}: ${e.message}\n`;
+            }
+            // Ambiguous names (duplicate classes, several ABC tags) get a marker so import finds the right class.
+            if (counts.get(name) > 1 || tags.length > 1)
+                text = `${exports.CLASS_MARKER} abc=${k} class=${c}\n${text}`;
+            const abs = (0, node_path_1.join)(outDir, ...rel.split('/'));
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(abs), { recursive: true });
+            await (0, promises_1.writeFile)(abs, text, 'utf8');
+            files.push(abs);
+        }
+    }
+    return { files, failed };
+}

package/dist/cjs/project/source-import.d.ts

@@ -0,0 +1,13 @@
+import { type CompiledMember } from '../compiler/class-compiler.js';
+import type { Swf } from '../swf/swf.js';
+export interface ImportSourcesResult {
+    changes: CompiledMember[];
+    /** Files that were parsed and matched no change. */
+    unchanged: number;
+}
+export interface ImportSourcesOptions {
+    /** Only import these files (absolute, or relative to `dir`). */
+    files?: string[];
+}
+/** Compiles `.as` files from `dir` (or explicit file paths) into the SWF. */
+export declare function importSources(swf: Swf, dir: string, options?: ImportSourcesOptions): Promise<ImportSourcesResult>;

package/dist/cjs/project/source-import.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importSources = importSources;
+/**
+ * Applies edited / new `.as` files to an SWF. Classes are matched by their
+ * fully qualified name; within existing classes only members whose text
+ * differs from the decompiled original are recompiled.
+ */
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const interner_js_1 = require("../abc/interner.js");
+const class_compiler_js_1 = require("../compiler/class-compiler.js");
+const parser_js_1 = require("../compiler/parser.js");
+const source_export_js_1 = require("./source-export.js");
+async function listAsFiles(dir) {
+    const out = [];
+    const walk = async (d) => {
+        for (const e of await (0, promises_1.readdir)(d, { withFileTypes: true })) {
+            const p = (0, node_path_1.join)(d, e.name);
+            if (e.isDirectory())
+                await walk(p);
+            else if (e.name.endsWith('.as'))
+                out.push(p);
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}
+/** Compiles `.as` files from `dir` (or explicit file paths) into the SWF. */
+async function importSources(swf, dir, options = {}) {
+    const files = options.files ? options.files.map((f) => (f.startsWith('/') ? f : (0, node_path_1.join)(dir, f))) : await listAsFiles(dir);
+    const tags = swf.abcTags;
+    if (!tags.length)
+        throw new Error('SWF has no ActionScript 3 code (no DoABC tag)');
+    const interners = new Map();
+    const result = { changes: [], unchanged: 0 };
+    const existing = [];
+    const added = [];
+    for (const file of files) {
+        const text = await (0, promises_1.readFile)(file, 'utf8');
+        const marker = new RegExp(`^${source_export_js_1.CLASS_MARKER.replace(/[/]/g, '\\/')} abc=(\\d+) class=(\\d+)`).exec(text);
+        if (marker) {
+            const tag = tags[Number(marker[1])];
+            if (!tag)
+                throw new Error(`${file}: ABC tag #${marker[1]} does not exist`);
+            existing.push({ file, text, tag, classIndex: Number(marker[2]) });
+            continue;
+        }
+        const unit = (0, parser_js_1.parseAs3)(text, (0, node_path_1.relative)(process.cwd(), file));
+        let target;
+        for (const cls of unit.classes) {
+            const q = unit.package ? `${unit.package}.${cls.name}` : cls.name;
+            target ??= tags.find((t) => t.abc.findClass(q) >= 0);
+        }
+        if (target)
+            existing.push({ file, text, tag: target });
+        else
+            added.push({ file, text, tag: tags[tags.length - 1] });
+    }
+    // Interfaces and base classes first among new files.
+    added.sort((a, b) => Number(/\binterface\b/.test(b.text)) - Number(/\binterface\b/.test(a.text)));
+    for (const p of [...existing, ...added]) {
+        let pool = interners.get(p.tag);
+        if (!pool)
+            interners.set(p.tag, (pool = new interner_js_1.Interner(p.tag.abc)));
+        const r = (0, class_compiler_js_1.compileClassSource)(p.tag.abc, p.text, { source: (0, node_path_1.relative)(process.cwd(), p.file), interner: pool, classIndex: p.classIndex });
+        if (r.changes.length)
+            result.changes.push(...r.changes);
+        else
+            result.unchanged++;
+    }
+    return result;
+}

package/dist/cjs/swf/swf.d.ts

@@ -0,0 +1,63 @@
+import { type PackOptions, type SwfCompression } from '../compression/swf-container.js';
+import { DefineSpriteTag, DoABCTag, Tag } from './tags.js';
+/** Rectangle in twips (1/20 pixel). */
+export interface Rect {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+}
+export interface SwfSaveOptions extends PackOptions {
+    /** Override the compression used when saving. Defaults to the original compression. */
+    compression?: SwfCompression;
+}
+/** An SWF file: header plus a list of tags. */
+export declare class Swf {
+    version: number;
+    compression: SwfCompression;
+    /** Stage bounds in twips. */
+    frameSize: Rect;
+    /** Frames per second (8.8 fixed point in the file). */
+    frameRate: number;
+    frameCount: number;
+    tags: Tag[];
+    /** Bytes after the End tag (normally empty). Preserved on save. */
+    trailing: Uint8Array;
+    private rectBits;
+    constructor(init?: {
+        version?: number;
+        compression?: SwfCompression;
+        frameSize?: Rect;
+        frameRate?: number;
+        frameCount?: number;
+        tags?: Tag[];
+    });
+    /** Parse an SWF file (FWS, CWS or ZWS). */
+    static parse(bytes: Uint8Array): Swf;
+    static load(path: string): Promise<Swf>;
+    /** Uncompressed SWF body (everything after the 8-byte file header). */
+    encodeBody(): Uint8Array;
+    /** Serialise to a complete SWF file. */
+    toBytes(options?: SwfSaveOptions): Uint8Array;
+    /**
+     * Write to disk. Uses a temporary file + rename, so saving over the source
+     * file is safe.
+     */
+    save(path: string, options?: SwfSaveOptions): Promise<void>;
+    get width(): number;
+    get height(): number;
+    /** Depth-first iteration over all tags, including tags nested in DefineSprite. */
+    walkTags(): Generator<{
+        tag: Tag;
+        parent: DefineSpriteTag | null;
+        index: number;
+    }>;
+    /** All DoABC / DoABC2 tags in file order. */
+    get abcTags(): DoABCTag[];
+    /** Character-defining tag with the given id (searches nested sprites too). */
+    findCharacter(id: number): Tag | undefined;
+    /** Merged SymbolClass mapping: class name → character id. */
+    symbolClasses(): Map<string, number>;
+    /** Main document class (SymbolClass entry with id 0), if any. */
+    get documentClass(): string | undefined;
+}

package/dist/cjs/swf/swf.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Swf = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const reader_js_1 = require("../io/reader.js");
+const writer_js_1 = require("../io/writer.js");
+const swf_container_js_1 = require("../compression/swf-container.js");
+const tags_js_1 = require("./tags.js");
+const tag_codes_js_1 = require("./tag-codes.js");
+function readRect(r) {
+    const bits = r.ub(5);
+    const rect = { xMin: r.sb(bits), xMax: r.sb(bits), yMin: r.sb(bits), yMax: r.sb(bits) };
+    r.align();
+    return { rect, bits };
+}
+function writeRect(w, rect, minBits = 0) {
+    const bits = Math.max(minBits, (0, writer_js_1.signedBits)(rect.xMin), (0, writer_js_1.signedBits)(rect.xMax), (0, writer_js_1.signedBits)(rect.yMin), (0, writer_js_1.signedBits)(rect.yMax));
+    w.ub(5, bits);
+    w.sb(bits, rect.xMin);
+    w.sb(bits, rect.xMax);
+    w.sb(bits, rect.yMin);
+    w.sb(bits, rect.yMax);
+    w.align();
+}
+/** An SWF file: header plus a list of tags. */
+class Swf {
+    version;
+    compression;
+    /** Stage bounds in twips. */
+    frameSize;
+    /** Frames per second (8.8 fixed point in the file). */
+    frameRate;
+    frameCount;
+    tags;
+    /** Bytes after the End tag (normally empty). Preserved on save. */
+    trailing;
+    rectBits;
+    constructor(init = {}) {
+        this.version = init.version ?? 10;
+        this.compression = init.compression ?? 'zlib';
+        this.frameSize = init.frameSize ?? { xMin: 0, xMax: 550 * 20, yMin: 0, yMax: 400 * 20 };
+        this.frameRate = init.frameRate ?? 24;
+        this.frameCount = init.frameCount ?? 1;
+        this.tags = init.tags ?? [];
+        this.trailing = new Uint8Array(0);
+        this.rectBits = 0;
+    }
+    // -------------------------------------------------------------------------
+    // Loading / saving
+    // -------------------------------------------------------------------------
+    /** Parse an SWF file (FWS, CWS or ZWS). */
+    static parse(bytes) {
+        const { compression, version, body } = (0, swf_container_js_1.unpackSwf)(bytes);
+        const r = new reader_js_1.ByteReader(body);
+        const { rect, bits } = readRect(r);
+        const frameRate = r.u16() / 256;
+        const frameCount = r.u16();
+        const { tags, end } = (0, tags_js_1.readTags)(body, r.pos, body.length);
+        const swf = new Swf({ version, compression, frameSize: rect, frameRate, frameCount, tags });
+        swf.rectBits = bits;
+        swf.trailing = body.slice(end);
+        return swf;
+    }
+    static async load(path) {
+        return Swf.parse(new Uint8Array(await (0, promises_1.readFile)(path)));
+    }
+    /** Uncompressed SWF body (everything after the 8-byte file header). */
+    encodeBody() {
+        const w = new writer_js_1.ByteWriter(1 << 16);
+        writeRect(w, this.frameSize, this.rectBits);
+        w.u16(Math.round(this.frameRate * 256));
+        w.u16(this.frameCount);
+        const tags = this.tags;
+        (0, tags_js_1.writeTags)(w, tags);
+        if (tags.length === 0 || tags[tags.length - 1].code !== tag_codes_js_1.TagCode.End) {
+            w.u16(0); // End tag
+        }
+        w.bytes(this.trailing);
+        return w.toBytes();
+    }
+    /** Serialise to a complete SWF file. */
+    toBytes(options = {}) {
+        return (0, swf_container_js_1.packSwf)({ compression: options.compression ?? this.compression, version: this.version, body: this.encodeBody() }, options);
+    }
+    /**
+     * Write to disk. Uses a temporary file + rename, so saving over the source
+     * file is safe.
+     */
+    async save(path, options = {}) {
+        const bytes = this.toBytes(options);
+        const tmp = (0, node_path_1.join)((0, node_path_1.dirname)(path), `.${(0, node_path_1.basename)(path)}.${process.pid}.${Date.now()}.tmp`);
+        await (0, promises_1.writeFile)(tmp, bytes);
+        await (0, promises_1.rename)(tmp, path);
+    }
+    // -------------------------------------------------------------------------
+    // Convenience accessors
+    // -------------------------------------------------------------------------
+    get width() {
+        return (this.frameSize.xMax - this.frameSize.xMin) / 20;
+    }
+    get height() {
+        return (this.frameSize.yMax - this.frameSize.yMin) / 20;
+    }
+    /** Depth-first iteration over all tags, including tags nested in DefineSprite. */
+    *walkTags() {
+        function* walk(list, parent) {
+            for (let i = 0; i < list.length; i++) {
+                const tag = list[i];
+                yield { tag, parent, index: i };
+                if (tag instanceof tags_js_1.DefineSpriteTag)
+                    yield* walk(tag.tags, tag);
+            }
+        }
+        yield* walk(this.tags, null);
+    }
+    /** All DoABC / DoABC2 tags in file order. */
+    get abcTags() {
+        return this.tags.filter((t) => t instanceof tags_js_1.DoABCTag);
+    }
+    /** Character-defining tag with the given id (searches nested sprites too). */
+    findCharacter(id) {
+        for (const { tag } of this.walkTags())
+            if (tag.characterId === id)
+                return tag;
+        return undefined;
+    }
+    /** Merged SymbolClass mapping: class name → character id. */
+    symbolClasses() {
+        const map = new Map();
+        for (const t of this.tags) {
+            if (t instanceof tags_js_1.SymbolTableTag && t.code === tag_codes_js_1.TagCode.SymbolClass) {
+                for (const s of t.symbols)
+                    map.set(s.name, s.id);
+            }
+        }
+        return map;
+    }
+    /** Main document class (SymbolClass entry with id 0), if any. */
+    get documentClass() {
+        for (const [name, id] of this.symbolClasses())
+            if (id === 0)
+                return name;
+        return undefined;
+    }
+}
+exports.Swf = Swf;

package/dist/cjs/swf/tag-codes.d.ts

@@ -0,0 +1,77 @@
+/** SWF tag codes (SWF File Format Specification v19). */
+export declare const TagCode: {
+    readonly End: 0;
+    readonly ShowFrame: 1;
+    readonly DefineShape: 2;
+    readonly FreeCharacter: 3;
+    readonly PlaceObject: 4;
+    readonly RemoveObject: 5;
+    readonly DefineBits: 6;
+    readonly DefineButton: 7;
+    readonly JPEGTables: 8;
+    readonly SetBackgroundColor: 9;
+    readonly DefineFont: 10;
+    readonly DefineText: 11;
+    readonly DoAction: 12;
+    readonly DefineFontInfo: 13;
+    readonly DefineSound: 14;
+    readonly StartSound: 15;
+    readonly DefineButtonSound: 17;
+    readonly SoundStreamHead: 18;
+    readonly SoundStreamBlock: 19;
+    readonly DefineBitsLossless: 20;
+    readonly DefineBitsJPEG2: 21;
+    readonly DefineShape2: 22;
+    readonly DefineButtonCxform: 23;
+    readonly Protect: 24;
+    readonly PlaceObject2: 26;
+    readonly RemoveObject2: 28;
+    readonly DefineShape3: 32;
+    readonly DefineText2: 33;
+    readonly DefineButton2: 34;
+    readonly DefineBitsJPEG3: 35;
+    readonly DefineBitsLossless2: 36;
+    readonly DefineEditText: 37;
+    readonly DefineSprite: 39;
+    readonly ProductInfo: 41;
+    readonly FrameLabel: 43;
+    readonly SoundStreamHead2: 45;
+    readonly DefineMorphShape: 46;
+    readonly DefineFont2: 48;
+    readonly ExportAssets: 56;
+    readonly ImportAssets: 57;
+    readonly EnableDebugger: 58;
+    readonly DoInitAction: 59;
+    readonly DefineVideoStream: 60;
+    readonly VideoFrame: 61;
+    readonly DefineFontInfo2: 62;
+    readonly DebugID: 63;
+    readonly EnableDebugger2: 64;
+    readonly ScriptLimits: 65;
+    readonly SetTabIndex: 66;
+    readonly FileAttributes: 69;
+    readonly PlaceObject3: 70;
+    readonly ImportAssets2: 71;
+    readonly DoABC: 72;
+    readonly DefineFontAlignZones: 73;
+    readonly CSMTextSettings: 74;
+    readonly DefineFont3: 75;
+    readonly SymbolClass: 76;
+    readonly Metadata: 77;
+    readonly DefineScalingGrid: 78;
+    readonly DoABC2: 82;
+    readonly DefineShape4: 83;
+    readonly DefineMorphShape2: 84;
+    readonly DefineSceneAndFrameLabelData: 86;
+    readonly DefineBinaryData: 87;
+    readonly DefineFontName: 88;
+    readonly StartSound2: 89;
+    readonly DefineBitsJPEG4: 90;
+    readonly DefineFont4: 91;
+    readonly EnableTelemetry: 93;
+    readonly PlaceObject4: 94;
+};
+export type TagCodeName = keyof typeof TagCode;
+export declare function tagName(code: number): string;
+/** Tags whose body starts with the u16 id of the character they define. */
+export declare const CHARACTER_DEFINING_TAGS: ReadonlySet<number>;