swf-toolkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recep Asan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# swf-toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** | [Türkçe](README.tr.md)
+
+[![npm](https://img.shields.io/npm/v/swf-toolkit.svg)](https://www.npmjs.com/package/swf-toolkit)
+[![CI](https://github.com/recepasan/swf-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/recepasan/swf-toolkit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/swf-toolkit.svg)](LICENSE)
+
+A pure TypeScript library and CLI for reading, editing and writing Adobe Flash SWF files. No Java or other external tools required.
+
+- **SWF:** Reads and writes FWS, CWS (zlib) and ZWS (LZMA). LZMA encoder and decoder included. Unmodified files are written back byte-for-byte.
+- **AS3 decompiler:** Produces readable ActionScript 3 source. Recovers if/else, loops, for-in/for-each, switch, try/catch and `&&`/`||`/ternary expressions.
+- **AS3 compiler:** Compiles edited or newly written `.as` files to AVM2 bytecode. Add methods and fields to existing classes, define new classes and interfaces, or build a SWF from scratch.
+- **AVM2 P-code:** Disassembler and assembler for bytecode-level editing. Constant pools, stack and scope limits are handled automatically.
+- **AS1/AS2 (AVM1):** Disassembler and assembler for DoAction/DoInitAction blocks.
+- **Assets:** Export and replace images (PNG/JPEG/GIF), sounds (MP3/WAV), binary data and text fields.
+
+Requires Node.js 18+. Ships both ESM (`import`) and CommonJS (`require()`) builds. No runtime dependencies.
+
+## Installation
+
+```bash
+npm install swf-toolkit        # as a library
+npm install -g swf-toolkit     # as a CLI (swf-toolkit command)
+npx swf-toolkit info game.swf  # run without installing
+```
+
+## CLI
+
+```bash
+# Inspect
+swf-toolkit info game.swf
+swf-toolkit classes game.swf
+swf-toolkit decompile game.swf com.foo.Bar
+swf-toolkit disasm game.swf com.foo.Bar init
+
+# Source-level AS3 editing
+swf-toolkit export-as3 game.swf ./src           # one .as file per class
+#   … edit files under ./src, add new .as files …
+swf-toolkit import-as3 game.swf ./src out.swf   # only changed members are compiled
+swf-toolkit compile game.swf out.swf New.as Other.as
+
+# Build a SWF from scratch
+swf-toolkit build app.swf Main.as lib/Helper.as --main Main --width 800 --height 600
+
+# Bytecode (P-code) editing
+swf-toolkit export-pcode game.swf ./pcode
+swf-toolkit import-pcode game.swf ./pcode out.swf
+
+# AS1/AS2
+swf-toolkit export-as2 old.swf ./as2
+swf-toolkit import-as2 old.swf ./as2 out.swf
+
+# Assets
+swf-toolkit export-assets game.swf ./assets            # images, sounds, binary, texts
+swf-toolkit replace game.swf out.swf 12 new.png 40 music.mp3
+
+# Compression
+swf-toolkit decompress game.swf plain.swf
+swf-toolkit compress plain.swf small.swf lzma
+```
+
+`import-as3` compares each class with the decompiled form of its current bytecode. Methods whose text has not changed keep their original bytecode, so code the decompiler cannot reproduce perfectly stays intact as long as you leave it alone. Methods that could not be decompiled are written with a `// Decompilation failed` comment and their P-code. They are never replaced with an empty body unless you write a new body yourself.
+
+## Library
+
+```ts
+import { Swf, decompileClass, compileClassSource, compileSources, createSwf } from 'swf-toolkit';
+
+const swf = await Swf.load('game.swf');
+const abc = swf.abcTags[0].abc;
+
+// Edit a class as AS3
+const ci = abc.findClass('com.foo.Bar');
+const src = decompileClass(abc, ci);
+const edited = src.replace('return 10;', 'return 99;');
+compileClassSource(abc, edited);              // only changed members are compiled
+await swf.save('game-patched.swf');
+
+// Build a SWF from scratch
+const { abc: fresh } = compileSources([{ name: 'Main.as', text: mainSource }]);
+await createSwf(fresh, { documentClass: 'Main' }).save('app.swf');
+```
+
+Other APIs:
+
+- P-code: `disassembleMethod`, `assembleMethod`, `exportPcode`, `importPcode`.
+- Bytecode tools: `decodeCode`, `encodeCode`, `computeLimits`, `verifyCode`.
+- Parser: `parseAs3`.
+- Assets: `exportAssets`, `replaceAsset`.
+- AVM1: `decodeActions`, `formatActions`, `parseActions`, `encodeActions`.
+
+## How the compiler resolves names
+
+Local variables and parameters are bound to registers. Variables captured by closures are stored in activation-object slots. Every other name is emitted as a `Multiname` with the class's open namespace set and resolved by the VM through the scope chain, which is what the Flex compiler does for names it cannot bind early. Type annotations (`var x:Foo`, parameters, return types) are resolved to QNames using imports, the same package, top-level classes and the SWF's own constant pool, so `playerglobal.swc` is not needed.
+
+For classes without a constructor, an implicit constructor is generated for non-constant field initialisers. As in Flex, these values are assigned before the `super()` call.
+
+Supported language features: classes, interfaces, inheritance, `super`, getters/setters, static members, constants, default and `...rest` parameters, closures, every loop form (including labelled break/continue), switch, try/catch/finally, `with`, regular expressions, Vector, object and array literals, `as`/`is`/`instanceof`/`in`/`typeof`/`delete`, compound assignments (including `&&=` and `||=`), E4X access (`.@attr`, `..child`, `.(filter)`) and XML literals (compiled to `new XML(...)` at runtime).
+
+## Tests
+
+```bash
+npm test
+```
+
+Tests use Node's built-in `node:test` module. They cover:
+
+- LZMA, SWF container and ABC round-trips, the P-code round-trip and the verifier.
+- The parser, the compiler and decompile → compile → decompile stability.
+- PNG, sound and AVM1 round-trips.
+
+If [Ruffle](https://ruffle.rs) is installed (`/Applications/Ruffle.app` or `RUFFLE=/path/to/ruffle`), the compiled test program runs in a real Flash VM and 59 runtime checks are verified. Without Ruffle this test is skipped.
+
+## Limitations
+
+- **No type checking.** Type errors only surface at runtime. Interface conformance and override signatures are not checked either.
+- **finally:** `finally` blocks are duplicated on the normal exit, `return`, `break` and `continue` paths.
+- **Namespace declarations:** Package-level namespace declarations (`public namespace x = "..."`) are not compiled. Existing namespaces can be used with `use namespace` and `ns::name`.
+- **XML literals:** `{expression}` interpolation is not supported.
+- **Decompiler:** Works well on Flex/ASC output. Methods that fail on obfuscated code are shown as P-code in comments.
+- **Assets:** Fonts and shape/sprite vector graphics are not converted and are kept as raw tags. JPEG3/4 alpha channels are exported as a separate mask PNG. Nellymoser and Speex sounds are exported as raw data.
+
+## License
+
+MIT

package/README.tr.md

@@ -0,0 +1,126 @@
+# swf-toolkit
+
+[English](README.md) | **Türkçe**
+
+[![npm](https://img.shields.io/npm/v/swf-toolkit.svg)](https://www.npmjs.com/package/swf-toolkit)
+[![CI](https://github.com/recepasan/swf-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/recepasan/swf-toolkit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/swf-toolkit.svg)](LICENSE)
+
+Adobe Flash SWF dosyalarını okumak, düzenlemek ve yeniden yazmak için saf TypeScript kütüphanesi ve CLI. Java ya da başka bir harici araç gerektirmez.
+
+- **SWF:** FWS, CWS (zlib) ve ZWS (LZMA) formatlarını okur ve yazar. LZMA kodlayıcı ve çözücü pakete dahil. Değiştirilmeyen dosyalar byte byte aynı yazılır.
+- **AS3 decompiler:** Okunabilir ActionScript 3 kaynağı üretir. if/else, döngüler, for-in/for-each, switch, try/catch ve `&&`/`||`/ternary yapılarını geri kurar.
+- **AS3 derleyici:** Düzenlenmiş ya da yeni yazılmış `.as` dosyalarını AVM2 bytecode'a derler. Var olan sınıflara yeni metod ve alan eklenebilir, yeni sınıf ve interface tanımlanabilir, sıfırdan SWF üretilebilir.
+- **AVM2 P-code:** Bytecode seviyesinde düzenleme için disassembler ve assembler. Sabit havuzlarını, stack ve scope hesaplarını otomatik yapar.
+- **AS1/AS2 (AVM1):** DoAction/DoInitAction blokları için disassembler ve assembler.
+- **Kaynaklar:** Görsel (PNG/JPEG/GIF), ses (MP3/WAV), binary veri ve metin alanlarını dışa aktarır ve değiştirir.
+
+Node.js 18+ gerekir. Paket hem ESM (`import`) hem CommonJS (`require()`) olarak gelir. Çalışma zamanında bağımlılığı yoktur.
+
+## Kurulum
+
+```bash
+npm install swf-toolkit        # kütüphane olarak
+npm install -g swf-toolkit     # CLI olarak (swf-toolkit komutu)
+npx swf-toolkit info oyun.swf  # kurmadan çalıştırmak için
+```
+
+## CLI
+
+```bash
+# İnceleme
+swf-toolkit info oyun.swf
+swf-toolkit classes oyun.swf
+swf-toolkit decompile oyun.swf com.foo.Bar
+swf-toolkit disasm oyun.swf com.foo.Bar init
+
+# AS3 kaynak seviyesinde düzenleme
+swf-toolkit export-as3 oyun.swf ./src           # her sınıf için .as dosyası
+#   … ./src altındaki dosyaları düzenle, yeni .as dosyaları ekle …
+swf-toolkit import-as3 oyun.swf ./src out.swf   # sadece değişen üyeler derlenir
+swf-toolkit compile oyun.swf out.swf Yeni.as Diger.as
+
+# Sıfırdan SWF
+swf-toolkit build app.swf Main.as lib/Helper.as --main Main --width 800 --height 600
+
+# Bytecode (P-code) seviyesinde düzenleme
+swf-toolkit export-pcode oyun.swf ./pcode
+swf-toolkit import-pcode oyun.swf ./pcode out.swf
+
+# AS1/AS2
+swf-toolkit export-as2 eski.swf ./as2
+swf-toolkit import-as2 eski.swf ./as2 out.swf
+
+# Kaynaklar
+swf-toolkit export-assets oyun.swf ./assets            # images, sounds, binary, texts
+swf-toolkit replace oyun.swf out.swf 12 yeni.png 40 muzik.mp3
+
+# Sıkıştırma
+swf-toolkit decompress oyun.swf acik.swf
+swf-toolkit compress acik.swf kucuk.swf lzma
+```
+
+`import-as3` her sınıfı mevcut bytecode'un decompile edilmiş haliyle karşılaştırır. Metni değişmeyen metodlar orijinal bytecode'larıyla kalır. Böylece decompiler'ın kusursuz geri kuramadığı kod, dokunulmadığı sürece bozulmaz. Decompile edilemeyen metodlar `// Decompilation failed` yorumu ve P-code ile yazılır. Bu metodlar elle yeni bir gövde yazılmadıkça hiçbir zaman boş gövdeyle değiştirilmez.
+
+## Kütüphane
+
+```ts
+import { Swf, decompileClass, compileClassSource, compileSources, createSwf } from 'swf-toolkit';
+
+const swf = await Swf.load('oyun.swf');
+const abc = swf.abcTags[0].abc;
+
+// Bir sınıfı AS3 olarak düzenle
+const ci = abc.findClass('com.foo.Bar');
+const src = decompileClass(abc, ci);
+const edited = src.replace('return 10;', 'return 99;');
+compileClassSource(abc, edited);              // sadece değişen üyeler derlenir
+await swf.save('oyun-patched.swf');
+
+// Sıfırdan SWF
+const { abc: fresh } = compileSources([{ name: 'Main.as', text: mainSource }]);
+await createSwf(fresh, { documentClass: 'Main' }).save('app.swf');
+```
+
+Diğer API'ler:
+
+- P-code: `disassembleMethod`, `assembleMethod`, `exportPcode`, `importPcode`.
+- Bytecode araçları: `decodeCode`, `encodeCode`, `computeLimits`, `verifyCode`.
+- Parser: `parseAs3`.
+- Kaynaklar: `exportAssets`, `replaceAsset`.
+- AVM1: `decodeActions`, `formatActions`, `parseActions`, `encodeActions`.
+
+## Derleyicinin isim çözümleme modeli
+
+Yerel değişkenler ve parametreler register'lara bağlanır. Closure'ların yakaladığı değişkenler activation nesnesindeki slotlara konur. Diğer bütün isimler, sınıfın açık namespace kümesiyle bir `Multiname` olarak üretilir ve VM tarafından scope zinciri üzerinden çözülür. Flex derleyicisi de önceden bağlayamadığı isimler için aynısını yapar. Tip açıklamaları (`var x:Foo`, parametreler, dönüş tipleri) import'lar, aynı paket, top-level sınıflar ve SWF'in kendi sabit havuzu kullanılarak QName'e çözülür. Bu sayede `playerglobal.swc` gerekmez.
+
+Kurucusu olmayan sınıflarda, sabit olmayan alan başlangıç değerleri için örtük bir kurucu üretilir. Bu değerler, Flex'te olduğu gibi `super()` çağrısından önce atanır.
+
+Desteklenen dil özellikleri: sınıflar, interface'ler, kalıtım, `super`, getter/setter, static üyeler, const, varsayılan ve `...rest` parametreleri, closure'lar, bütün döngü türleri (etiketli break/continue dahil), switch, try/catch/finally, `with`, regex, Vector, nesne ve dizi literal'leri, `as`/`is`/`instanceof`/`in`/`typeof`/`delete`, bileşik atamalar (`&&=` ve `||=` dahil), E4X erişimleri (`.@attr`, `..child`, `.(filtre)`) ve XML literal'leri (çalışma zamanında `new XML(...)` olarak).
+
+## Testler
+
+```bash
+npm test
+```
+
+Testler Node'un yerleşik `node:test` modülüyle yazıldı. Kapsadıkları:
+
+- LZMA, SWF container ve ABC round-trip'leri, P-code round-trip'i ve doğrulayıcı.
+- Parser, derleyici ve decompile → derle → decompile kararlılığı.
+- PNG, ses ve AVM1 round-trip'leri.
+
+[Ruffle](https://ruffle.rs) kuruluysa (`/Applications/Ruffle.app` ya da `RUFFLE=/yol/ruffle`) derlenen test programı gerçek bir Flash VM'de çalıştırılır ve 59 çalışma zamanı kontrolü doğrulanır. Ruffle yoksa bu test atlanır.
+
+## Sınırlamalar
+
+- **Derleyici tip denetimi yapmaz.** Tip hataları ancak çalışma zamanında ortaya çıkar. Arayüz uyumu ve override imzaları da denetlenmez.
+- **finally:** `finally` blokları normal çıkış, `return`, `break` ve `continue` yollarına kopyalanır.
+- **Namespace bildirimi:** Paket seviyesinde namespace bildirimleri (`public namespace x = "..."`) derlenmez. Var olan namespace'ler `use namespace` ve `ns::isim` ile kullanılabilir.
+- **XML literal'leri:** `{ifade}` gömme desteklenmez.
+- **Decompiler:** Flex/ASC çıktısında iyi sonuç verir. Obfuscate edilmiş kodda başarısız olan metodlar P-code olarak yorum satırında gösterilir.
+- **Kaynaklar:** Fontlar ve shape/sprite vektör çizimleri dönüştürülmez, ham tag olarak korunur. JPEG3/4 alfa kanalı ayrı bir maske PNG'si olarak dışa aktarılır. Nellymoser ve Speex sesleri ham veri olarak çıkarılır.
+
+## Lisans
+
+MIT

package/dist/abc/abc-file.d.ts

@@ -0,0 +1,168 @@
+export interface NamespaceInfo {
+    kind: number;
+    /** String pool index (0 = no name). */
+    name: number;
+}
+/**
+ * A multiname pool entry. Only the fields relevant for `kind` are meaningful:
+ * - QName(A): ns, name
+ * - RTQName(A): name
+ * - RTQNameL(A): –
+ * - Multiname(A): name, nsSet
+ * - MultinameL(A): nsSet
+ * - TypeName: base, params
+ */
+export interface MultinameInfo {
+    kind: number;
+    ns: number;
+    name: number;
+    nsSet: number;
+    base: number;
+    params: number[];
+}
+export interface OptionalParam {
+    kind: number;
+    value: number;
+}
+export interface MethodInfo {
+    paramTypes: number[];
+    returnType: number;
+    name: number;
+    flags: number;
+    optional: OptionalParam[];
+    paramNames: number[];
+}
+export interface MetadataInfo {
+    name: number;
+    keys: number[];
+    values: number[];
+}
+export interface Trait {
+    name: number;
+    kind: number;
+    /** Upper 4 bits of the kind byte (Final / Override / Metadata). */
+    attrs: number;
+    /** slot_id for Slot/Const/Class/Function, disp_id for Method/Getter/Setter. */
+    id: number;
+    /** Slot/Const: type multiname. */
+    typeName: number;
+    /** Slot/Const: default value index (0 = none). */
+    valueIndex: number;
+    /** Slot/Const: default value kind (only if valueIndex != 0). */
+    valueKind: number;
+    /** Class: class index. */
+    classIndex: number;
+    /** Method/Getter/Setter/Function: method index. */
+    method: number;
+    metadata: number[];
+}
+export interface InstanceInfo {
+    name: number;
+    superName: number;
+    flags: number;
+    protectedNs: number;
+    interfaces: number[];
+    iinit: number;
+    traits: Trait[];
+}
+export interface ClassInfo {
+    cinit: number;
+    traits: Trait[];
+}
+export interface ScriptInfo {
+    init: number;
+    traits: Trait[];
+}
+export interface ExceptionInfo {
+    from: number;
+    to: number;
+    target: number;
+    excType: number;
+    varName: number;
+}
+export interface MethodBody {
+    method: number;
+    maxStack: number;
+    localCount: number;
+    initScopeDepth: number;
+    maxScopeDepth: number;
+    code: Uint8Array;
+    exceptions: ExceptionInfo[];
+    traits: Trait[];
+}
+export declare function emptyMultiname(kind?: number): MultinameInfo;
+export declare function newTrait(partial: Partial<Trait> & {
+    name: number;
+    kind: number;
+}): Trait;
+/** A parsed ActionScript Byte Code (ABC) file. */
+export declare class AbcFile {
+    minorVersion: number;
+    majorVersion: number;
+    ints: number[];
+    uints: number[];
+    doubles: number[];
+    strings: string[];
+    namespaces: NamespaceInfo[];
+    nsSets: number[][];
+    multinames: MultinameInfo[];
+    methods: MethodInfo[];
+    metadata: MetadataInfo[];
+    instances: InstanceInfo[];
+    classes: ClassInfo[];
+    scripts: ScriptInfo[];
+    bodies: MethodBody[];
+    /** Raw bytes of strings that are not valid UTF-8, keyed by pool index. */
+    private rawStrings;
+    /** Pools whose count was written as 1 (instead of 0) while empty; preserved for exact round-trips. */
+    private onePools;
+    private readonly intCache;
+    private readonly uintCache;
+    private readonly doubleCache;
+    private readonly stringCache;
+    private readonly nsCache;
+    private readonly nsSetCache;
+    private readonly mnCache;
+    private bodyIndex;
+    private bodyIndexSize;
+    static parse(bytes: Uint8Array): AbcFile;
+    toBytes(): Uint8Array;
+    /** String pool index for `s` (adds it if missing). */
+    string(s: string): number;
+    int(v: number): number;
+    uint(v: number): number;
+    double(v: number): number;
+    /** Namespace pool index. `PrivateNs` entries are always created fresh unless `reuse` is set. */
+    namespace(kind: number, name: string | number, reuse?: boolean): number;
+    packageNamespace(name: string): number;
+    nsSet(namespaces: number[]): number;
+    multiname(info: Partial<MultinameInfo> & {
+        kind: number;
+    }): number;
+    /** QName multiname index. `ns` may be a namespace index or a package name. */
+    qname(ns: number | string, name: string): number;
+    /** QName for a fully qualified name like "flash.display.Sprite" (or "flash.display:Sprite"). */
+    qnameFor(qualified: string): number;
+    /** Method body for a method index, if the method has one. */
+    methodBody(methodIndex: number): MethodBody | undefined;
+    /** Namespace URI string (empty for the public/unnamed namespace). */
+    namespaceName(nsIndex: number): string;
+    /** Local name of a multiname ("*" if any). */
+    multinameName(mnIndex: number): string;
+    /**
+     * Fully qualified dotted name of a multiname, e.g. "flash.display.Sprite".
+     * For non-QName multinames this is just the local name.
+     */
+    qualifiedName(mnIndex: number): string;
+    /** Fully qualified name of class `classIndex`. */
+    className(classIndex: number): string;
+    /** Class index by fully qualified name ("com.example.Foo" or "com.example:Foo"); -1 if not found. */
+    findClass(qualified: string): number;
+    /** Names of all classes defined in this ABC. */
+    classNames(): string[];
+}
+/** Split "a.b.C" / "a.b:C" into package and local name. */
+export declare function splitQualifiedName(qualified: string): {
+    pkg: string;
+    name: string;
+};