@turbowarp/types 0.0.14 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turbowarp/types",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Type definitions for the Scratch VM and editor",
   "keywords": [
     "scratch"

package/types/events.d.ts

@@ -6,6 +6,7 @@ type EventEmitterCallback<Events, K extends keyof Events> = (...args: Events[K]
 
 declare class EventEmitter<Events> {
   on<K extends keyof Events>(event: K, callback: EventEmitterCallback<Events, K>): void;
+  addListener<K extends keyof Events>(event: K, callback: EventEmitterCallback<Events, K>): void;
   once<K extends keyof Events>(event: K, callback: EventEmitterCallback<Events, K>): void;
   off<K extends keyof Events>(event: K, callback: EventEmitterCallback<Events, K>): void;
   removeListener<K extends keyof Events>(event: K, callback: EventEmitterCallback<Events, K>): void;

package/types/scratch-audio.d.ts

@@ -14,7 +14,9 @@ declare namespace AudioEngine {
     mic: MediaStreamAudioSourceNode;
 
     /**
-     * @returns Loudness measured from 0-100.
+     * Get the current loudness of sound received by the microphone.
+     * Sound is measured in RMS and smoothed.
+     * @returns Loudness scaled 0 to 100, or -1 if there is no microphone input.
      */
     getLoudness(): number;
   }
@@ -32,7 +34,7 @@ declare namespace AudioEngine {
     target: Target;
     connect(target: Target): void;
     get name(): string;
-    get DEFAULT_VALUE(): string;
+    get DEFAULT_VALUE(): number;
     get _isPatch(): boolean;
     _set(value: number): void;
     set(value: number): void;
@@ -44,6 +46,10 @@ declare namespace AudioEngine {
   interface PitchEffect extends AbstractEffect {
     get name(): 'pitch';
     ratio: number;
+    /**
+     * The playback ratio is scaled so that a change of 10 in the effect value
+     * gives a change of 1 semitone in the ratio.
+     */
     getRatio(val: number): number;
     updatePlayer(soundPlayer: SoundPlayer): void;
     updatePlayers(soundPlayers: Record<string, SoundPlayer> | SoundPlayer[]): void;
@@ -101,6 +107,10 @@ declare namespace AudioEngine {
     isStarting: boolean;
     isPlaying: boolean;
     startingUntil: number;
+    playbackRate: number;
+    volumeEffect: VolumeEffect | null;
+    target: AudioEngine | Effect | EffectChain | null;
+    initialized: boolean;
     handleEvent(event: Event): void;
     onEnded(): void;
     _createSource(): void;
@@ -112,7 +122,7 @@ declare namespace AudioEngine {
     finished(): Promise<void>;
     setPlaybackRate(playbackRate: number): void;
     take(): SoundPlayer;
-    connect(connectable: AudioEngine | Effect | EffectChain): void;
+    connect(connectable: AudioEngine | Effect | EffectChain): SoundPlayer | undefined;
   }
 
   interface SoundBank {
@@ -144,7 +154,7 @@ declare namespace AudioEngine {
     playSound(target: Target, soundId: string): Promise<void>;
     setEffects(target: Target): void;
     stop(target: Target, soundId: string): void;
-    stopAllSounds(target: Target | '*'): void;
+    stopAllSounds(target?: Target | '*'): void;
     dispose(): void;
   }
 

package/types/scratch-blocks.d.ts

@@ -2,6 +2,9 @@
 // Project: https://github.com/LLK/scratch-blocks
 
 declare namespace ScratchBlocks {
+  const Blocks: Record<string, unknown>;
+  const Msg: Record<string, string>;
+
   class Block {
 
   }
@@ -178,6 +181,14 @@ declare namespace ScratchBlocks {
   interface BlocklyGlobal {
     getMainWorkspace(): Workspace | null;
   }
+
+  function prompt(
+    message: string,
+    defaultValue: string,
+    callback: (value: string | null) => void,
+    title?: string,
+    varType?: string
+  ): void;
 }
 
 declare const Blockly: ScratchBlocks.BlocklyGlobal | undefined;

package/types/scratch-render.d.ts

@@ -24,6 +24,7 @@ declare namespace RenderWebGL {
     Fisheye = 'fisheye',
     Whirl = 'whirl',
     Pixelate = 'pixelate',
+    Mosaic = 'mosaic',
     Brightness = 'brightness',
     Ghost = 'ghost'
   }
@@ -56,6 +57,11 @@ declare namespace RenderWebGL {
     snapToInt(): void;
   }
 
+  namespace Rectangle {
+    function intersect(a: Rectangle, b: Rectangle, result?: Rectangle): Rectangle;
+    function union(a: Rectangle, b: Rectangle, result?: Rectangle): Rectangle;
+  }
+
   /**
    * Suggested properties of a drawing region. Strictly, this can really be whatever you want it to be.
    */
@@ -79,7 +85,7 @@ declare namespace RenderWebGL {
     static DRAW_MODE: Record<DrawMode, DrawMode>;
 
     _gl: AnyWebGLContext;
-    _shaderCache: Record<DrawMode, Record<EffectMask, twgl.ProgramInfo[]>>;
+    _shaderCache: Record<DrawMode, twgl.ProgramInfo[]>;
     _buildShader(drawMode: DrawMode, effectMask: EffectMask): twgl.ProgramInfo;
     getShader(drawMode: DrawMode, effectMask: EffectMask): twgl.ProgramInfo;
   }
@@ -102,8 +108,8 @@ declare namespace RenderWebGL {
     colorAtNearest(textureCoordinate: twgl.V3, destination?: Uint8ClampedArray): Uint8ClampedArray;
     colorAtLinear(textureCoordinate: twgl.V3, destination?: Uint8ClampedArray): Uint8ClampedArray;
 
-    isTouchingNearest(textureCoordinate: twgl.V3): void;
-    isTouchingLinear(textureCoordinate: twgl.V3): void;
+    isTouchingNearest(textureCoordinate: twgl.V3): boolean;
+    isTouchingLinear(textureCoordinate: twgl.V3): boolean;
   }
 
   interface SkinEventMap {
@@ -131,7 +137,7 @@ declare namespace RenderWebGL {
       u_skinSize: [number, number];
       u_skin: WebGLTexture | null;
     };
-    getUniforms(): Skin['_uniforms'];
+    getUniforms(scale?: [number, number]): Skin['_uniforms'];
 
     _silhouette: Silhouette;
     updateSilhouette(): void;
@@ -148,11 +154,15 @@ declare namespace RenderWebGL {
 
     useNearest(scale: [number, number], drawable: Drawable): boolean;
 
-    getTexture(scale: [number, number]): WebGLTexture;
+    getTexture(scale?: [number, number]): WebGLTexture;
     _setTexture(image: BitmapData): void;
     setEmptyImageData(): void;
 
-    getFenceBounds(): Rectangle;
+    /**
+     * Get the bounds of the drawable for determining its fenced position.
+     * For compatibility with Scratch 2, we always use getAABB.
+     */
+    getFenceBounds(drawable: Drawable, result?: Rectangle): Rectangle;
 
     dispose(): void;
   }
@@ -201,15 +211,15 @@ declare namespace RenderWebGL {
     /**
      * Pen color in RGBA from 0-1.
      */
-    color4f: [number, number, number, number];
-    diameter: number;
+    color4f?: [number, number, number, number];
+    diameter?: number;
   }
 
   class PenSkin extends Skin {
     _renderer: RenderWebGL;
 
     _size: [number, number];
-    _framebuffer: WebGLFramebuffer;
+    _framebuffer: twgl.FrameBufferInfo;
     _silhouetteDirty: boolean;
     _silhouettePixels: Uint8Array;
     _silhouetteImageData: ImageData;
@@ -272,6 +282,7 @@ declare namespace RenderWebGL {
       width: number;
       height: number
     };
+    _text: string;
     _bubbleType: TextBubbleType;
     _pointsLeft: boolean;
     _textDirty: boolean;
@@ -324,7 +335,7 @@ declare namespace RenderWebGL {
 
     _scale: twgl.V3;
     get scale(): twgl.V3;
-    updateScale(scale: number): void;
+    updateScale(scale: [number, number]): void;
 
     _direction: number;
     updateDirection(direction: number): void;
@@ -361,7 +372,7 @@ declare namespace RenderWebGL {
     _convexHullPoints: Array<[number, number]>;
     _convexHullDirty: boolean;
     needsConvexHullPoints(): boolean;
-    setConvexHullDirty(): boolean;
+    setConvexHullDirty(): void;
     setConvexHullPoints(points: Array<[number, number]>): void;
 
     _transformedHullPoints: Array<[number, number]>;
@@ -380,6 +391,11 @@ declare namespace RenderWebGL {
     getFastBounds(result?: Rectangle): Rectangle;
 
     updateCPURenderAttributes(): void;
+    /**
+     * Check if the world position touches the skin.
+     * The caller is responsible for ensuring this drawable's inverse matrix & its skin's silhouette are up-to-date.
+     * @see updateCPURenderAttributes
+     */
     isTouching(textureCoordinate: twgl.V3): boolean;
     _isTouchingNearest(textureCoordinate: twgl.V3): boolean;
     _isTouchingLinear(textureCoordinate: twgl.V3): boolean;
@@ -556,7 +572,7 @@ declare class RenderWebGL extends EventEmitter<RenderWebGL.ScratchRenderEventMap
   pick(centerX: number, centerY: number, width?: number, height?: number, candidateIds?: number[]): number | -1 | false;
 
   extractDrawableScreenSpace(drawableId: number): {
-    data: ImageData;
+    imageData: ImageData;
     x: number;
     y: number;
     width: number;

package/types/scratch-storage.d.ts

@@ -17,7 +17,8 @@ declare namespace ScratchStorage {
     contentType: string;
     name: string;
     runtimeFormat: DataFormat;
-    immutable: true;
+    /** Indicates if the asset id is determined by the asset content. */
+    immutable: boolean;
   }
   namespace AssetType {
     const ImageBitmap: AssetType;
@@ -39,6 +40,8 @@ declare namespace ScratchStorage {
      */
     assetId: string;
 
+    data: Uint8Array;
+
     setData(data: Uint8Array, dataFormat: DataFormat, generateId?: boolean): void;
     encodeTextData(text: string, dataFormat: DataFormat, generateId?: boolean): void;
 
@@ -54,6 +57,7 @@ declare namespace ScratchStorage {
   type UrlFunction = (asset: Asset) => string;
 
   interface Helper {
+    parent: ScratchStorage;
     load(assetType: AssetType, assetId: string, dataFormat: DataFormat): Promise<Asset>;
     store(assetType: AssetType, dataFormat: DataFormat, data: Uint8Array, assetId: string): Promise<unknown>;
   }
@@ -76,7 +80,10 @@ declare class ScratchStorage {
 
   load(assetType: ScratchStorage.AssetType, assetId: string, dataFormat: ScratchStorage.DataFormat): Promise<ScratchStorage.Asset | null>;
 
-  store(assetType: ScratchStorage.Asset, dataFormat: ScratchStorage.DataFormat, data: Uint8Array, assetId: string): Promise<unknown>;
+  store(assetType: ScratchStorage.AssetType, dataFormat: ScratchStorage.DataFormat, data: Uint8Array, assetId: string): Promise<unknown>;
+
+  getDefaultAssetId(type: ScratchStorage.AssetType): string | undefined;
+  setDefaultAssetId(type: ScratchStorage.AssetType, id: string): void;
 
   createAsset(assetType: ScratchStorage.AssetType, dataFormat: ScratchStorage.DataFormat, data: Uint8Array, assetId: null, generateId: true): ScratchStorage.Asset;
   createAsset(assetType: ScratchStorage.AssetType, dataFormat: ScratchStorage.DataFormat, data: Uint8Array, assetId: string, generateId?: boolean): ScratchStorage.Asset;

package/types/scratch-vm.d.ts

@@ -45,6 +45,8 @@ declare namespace VM {
      */
     md5?: string;
 
+    md5ext?: string;
+
     name: string;
 
     asset: ScratchStorage.Asset;
@@ -75,6 +77,32 @@ declare namespace VM {
     sounds: Sound[];
     clones: RenderedTarget[];
     soundBank: AudioEngine.SoundBank | null;
+
+    /**
+     * Create a clone of this sprite.
+     * @param optLayerGroup Optional layer group the clone's drawable should be added to. Defaults to the sprite layer group.
+     */
+    createClone(optLayerGroup?: string): RenderedTarget;
+
+    duplicate(): Promise<Sprite>;
+
+    /**
+     * Add a costume at the given index, taking care to avoid duplicate names.
+     */
+    addCostumeAt(costumeObject: Costume, index: number): void;
+
+    /**
+     * Delete a costume by index.
+     * @returns The deleted costume, or undefined if none existed at that index.
+     */
+    deleteCostumeAt(index: number): Costume | undefined;
+
+    /**
+     * Disconnect a clone from this sprite. The clone is unmodified; in particular its dispose() is not called.
+     */
+    removeClone(clone: RenderedTarget): void;
+
+    dispose(): void;
   }
 
   interface Field {
@@ -145,11 +173,21 @@ declare namespace VM {
 
     getBlock(id: string): Block | undefined;
 
-    getOpcode(id: string): string | null;
+    getOpcode(block: Block): string | null;
 
-    getFields(id: string): object | null;
+    getFields(block: Block): Record<string, Field> | null;
 
-    getInputs(id: string): object | null;
+    getInputs(block: Block): Record<string, Input> | null;
+
+    getMutation(block: Block): ProcedureCallMutation | ProcedurePrototypeMutation | null;
+
+    getScripts(): string[];
+
+    getNextBlock(id: string): string | null;
+
+    getBranch(id: string, branchNum?: number): string | null;
+
+    getTopLevelScript(id: string): string | null;
 
     getProcedureDefinition(procedureCode: string): string | null;
 
@@ -230,6 +268,7 @@ declare namespace VM {
     y: number;
     width: number;
     height: number;
+    toXML(): string;
   }
 
   interface PostedSpriteInfo {
@@ -338,6 +377,77 @@ declare namespace VM {
      */
     createVariable(id: string, name: string, type: VariableType, isCloud?: boolean): void;
 
+    /**
+     * Renames the variable with the given id to newName.
+     */
+    renameVariable(id: string, newName: string): void;
+
+    /**
+     * Removes the variable with the given id from the dictionary of variables.
+     */
+    deleteVariable(id: string): void;
+
+    /**
+     * Create a clone of the variable with the given id.
+     * Returns null if the original variable was not found.
+     */
+    duplicateVariable(id: string, optKeepOriginalId?: boolean): Variable | null;
+
+    /**
+     * Duplicate the dictionary of this target's variables as part of duplicating this target or making a clone.
+     */
+    duplicateVariables(optBlocks?: Blocks): Record<string, Variable>;
+
+    /**
+     * Remove this target's monitors from the runtime state and remove the
+     * target-specific monitored blocks (e.g. local variables, x-position).
+     * Does not delete stage monitors like backdrop name.
+     */
+    deleteMonitors(): void;
+
+    /**
+     * Get the names of all the variables of the given type that are in scope for this target.
+     * @param type Defaults to the scalar type.
+     * @param skipStage Optional flag to skip the stage.
+     */
+    getAllVariableNamesInScopeByType(type?: VariableType, skipStage?: boolean): string[];
+
+    /**
+     * Merge variable references with another variable.
+     */
+    mergeVariables(idToBeMerged: string, idToMergeWith: string, optReferencesToUpdate?: object[], optNewName?: string): void;
+
+    /**
+     * Fixes up variable references in this target avoiding conflicts with
+     * pre-existing variables in the same scope. Used when uploading a target as a new sprite.
+     */
+    fixUpVariableReferences(): void;
+
+    /**
+     * Share the given variable-referencing fields with the target of the given id, resolving conflicts.
+     */
+    resolveVariableSharingConflictsWithTarget(blocks: Block[], receivingTarget: Target): void;
+
+    /**
+     * Share a local variable (and given references for that variable) to the stage.
+     */
+    shareLocalVariableToStage(varId: string, varRefs: object[]): void;
+
+    /**
+     * Share a local variable with a sprite, merging with one of the same name and type if it exists.
+     */
+    shareLocalVariableToSprite(varId: string, sprite: Target, varRefs: object[]): void;
+
+    /**
+     * Update an edge-activated hat block value.
+     * @return The old value for the edge-activated hat.
+     */
+    updateEdgeActivatedValue(blockId: string, newValue: unknown): unknown;
+
+    hasEdgeActivatedValue(blockId: string): boolean;
+
+    clearEdgeActivatedValues(): void;
+
     _customState: Partial<CustomState>;
     getCustomState<T extends keyof CustomState>(name: T): CustomState[T] | undefined;
     setCustomState<T extends keyof CustomState>(name: T, value: CustomState[T]): void;
@@ -353,7 +463,7 @@ declare namespace VM {
   }
 
   const enum RotationStyle {
-    AllAround = 'all-around',
+    AllAround = 'all around',
     LeftRight = 'left-right',
     None = "don't rotate"
   }
@@ -396,6 +506,8 @@ declare namespace VM {
 
     isStage: boolean;
 
+    dragging: boolean;
+
     /**
      * Returns true if the target is not the stage and is not a clone.
      */
@@ -411,7 +523,7 @@ declare namespace VM {
      */
     setXY(x: number, y: number, force?: boolean): void;
 
-    keepInFence(newX: number, newY: number, fence?: SimpleRectangle): [number, number];
+    keepInFence(newX: number, newY: number, fence?: SimpleRectangle): [number, number] | undefined;
 
     /**
      * Direction in degrees. Defaults to 90 (right). Can be from -179 to 180.
@@ -589,7 +701,7 @@ declare namespace VM {
     tempo: number;
 
     videoTransparency: number;
-
+    videoState: 'off' | 'on' | 'on-flipped';
 
     /**
      * Create a clone of this sprite if the clone limit has not been reached.
@@ -609,6 +721,23 @@ declare namespace VM {
 
     updateAllDrawableProperties(): void;
 
+    /**
+     * The language to use for speech synthesis, in the text2speech extension.
+     * Initialized to null; on extension load it may be set from the editor locale.
+     */
+    textToSpeechLanguage: string | null;
+
+    /**
+     * Create a drawable with this.renderer.
+     * @param layerGroup The layer group this drawable should be added to (a StageLayering value).
+     */
+    initDrawable(layerGroup: string): void;
+
+    /**
+     * Initialize the audio player for this sprite or clone.
+     */
+    initAudio(): void;
+
     toJSON(): SerializedTarget;
   }
 
@@ -630,7 +759,7 @@ declare namespace VM {
     waitingReporter: unknown;
     params: unknown;
     executionContext: unknown;
-    reset(): void;
+    reset(): StackFrame;
   }
 
   interface BlockUtility {
@@ -661,14 +790,18 @@ declare namespace VM {
      * @see {Thread.stopThisScript}
      */
     stopThisScript(): void;
+    /**
+     * @see {Sequencer.stepToProcedure}
+     */
+    startProcedure(procedureCode: string): void;
     /**
      * @see {Blocks.getProcedureParamNamesAndIds}
      */
-    getProcedureParamNamesAndIds(): [string[], string[]];
+    getProcedureParamNamesAndIds(procedureCode: string): [string[], string[]];
     /**
      * @see {Blocks.getProcedureParamNamesIdsAndDefaults}
      */
-    getProcedureParamNamesIdsAndDefaults(): [string[], string[], string[]];
+    getProcedureParamNamesIdsAndDefaults(procedureCode: string): [string[], string[], string[]];
     /**
      * @see {Thread.initParams}
      */
@@ -712,7 +845,7 @@ declare namespace VM {
     reuseStackForNextBlock(blockId: string): void;
     pushStack(blockId: string): void;
     popStack(): string;
-    peekStack(): string;
+    peekStack(): string | null;
     peekStackFrame(): StackFrame | null;
     peekParentStackFrame(): StackFrame | null;
     pushReportedValue(value: ScratchCompatibleValue): void;
@@ -763,17 +896,17 @@ declare namespace VM {
     start(id: number, arg: unknown): void;
     stop(): void;
     increment(id: number): void;
-    frame(id: string, arg: unknown): ProfilerFrame;
+    frame(id: number, arg: unknown): ProfilerFrame;
     reportFrames(): void;
     idByName(name: string): number;
-    nameById(id: number): string;
+    nameById(id: number): string | null;
   }
 
   interface Sequencer {
     timer: Timer;
     runtime: Runtime;
     activeThread: Thread | null;
-    stepThreads(): void;
+    stepThreads(): Thread[];
     stepThread(thread: Thread): void;
     stepToBranch(thread: Thread, branch: number, isLoop: boolean): void;
     stepToProcedure(thread: Thread, procedureCode: string): void;
@@ -781,12 +914,13 @@ declare namespace VM {
   }
 
   interface ImportedExtensionsInfo {
-    extensionIDs: string[];
-    extensionURLs: string[];
+    extensionIDs: Set<string>;
+    extensionURLs: Map<string, string>;
   }
 
   interface ExtensionManager {
     runtime: Runtime;
+    _loadedExtensions: Map<string, string>;
 
     refreshBlocks(): Promise<void[]>;
 
@@ -810,9 +944,9 @@ declare namespace VM {
   interface Timer {
     startTime: number;
 
-    time(): number;
+    nowObj: { now(): number };
 
-    relativeTime(): number;
+    time(): number;
 
     start(): void;
 
@@ -901,6 +1035,7 @@ declare namespace VM {
     canvasWidth?: number;
     canvasHeight?: number;
     isDown?: boolean;
+    wasDragged?: boolean;
   }
 
   interface Mouse {
@@ -944,11 +1079,44 @@ declare namespace VM {
   }
 
   interface VideoData {
-    // TODO
+    forceTransparentPreview: boolean;
   }
 
   interface Video {
-    // TODO
+    runtime: Runtime;
+    provider: VideoProvider | null;
+    _drawable: number;
+    _skinId: number;
+    mirror?: boolean;
+    readonly videoReady: boolean;
+
+    enableVideo(): Promise<void> | null;
+    disableVideo(): void;
+
+    getFrame(frameInfo: {
+      dimensions?: [number, number];
+      mirror?: boolean;
+      format?: 'image-data';
+      cacheTimeout?: number;
+    }): ImageData | null;
+    getFrame(frameInfo: {
+      dimensions?: [number, number];
+      mirror?: boolean;
+      format?: 'canvas';
+      cacheTimeout?: number;
+    }): HTMLCanvasElement | null;
+    getFrame(frameInfo: {
+      dimensions?: [number, number];
+      mirror?: boolean;
+      format?: 'image-data' | 'canvas' | string;
+      cacheTimeout?: number;
+    }): ImageData | HTMLCanvasElement | string | null;
+
+    /**
+     * @param ghost from 0 (visible) to 100 (invisible)
+     */
+    setPreviewGhost(ghost: number): void;
+
     postData(data: VideoData): void;
   }
 
@@ -1127,6 +1295,11 @@ declare namespace VM {
      */
     compatibilityMode: boolean;
 
+    /**
+     * Set whether the runtime is in 30 TPS "compatibility mode".
+     */
+    setCompatibilityMode(compatibilityMode: boolean): void;
+
     renderer: IfRenderer<RenderWebGL, undefined>;
 
     attachRenderer(renderer: RenderWebGL): void;
@@ -1237,6 +1410,22 @@ declare namespace VM {
 
     monitorBlocks: Blocks;
 
+    monitorBlockInfo: Record<string, unknown>;
+
+    requestAddMonitor(monitor: unknown): void;
+
+    requestUpdateMonitor(delta: unknown): boolean;
+
+    requestRemoveMonitor(monitorId: string): void;
+
+    requestHideMonitor(monitorId: string): boolean;
+
+    requestShowMonitor(monitorId: string): boolean;
+
+    requestRemoveMonitorByTargetId(targetId: string): void;
+
+    addMonitorScript(topBlockId: string, optTarget?: Target): void;
+
     visualReport(blockId: string, value: any): void;
 
     _primitives: Record<string, Function>;
@@ -1253,6 +1442,8 @@ declare namespace VM {
       xml: string;
     }>;
 
+    getBlocksJSON(): object[];
+
     _blockInfo: ExtensionInfo[];
 
     _hats: Record<string, HatInfo>;
@@ -1339,6 +1530,8 @@ declare namespace VM {
 
     emitProjectLoaded(): void;
 
+    handleProjectLoaded(): void;
+
     emitProjectChanged(): void;
 
     _editingTarget: Target | null;
@@ -1354,6 +1547,16 @@ declare namespace VM {
 
     getPeripheralIsConnected(extensionID: string): boolean;
 
+    peripheralExtensions: Record<string, unknown>;
+
+    registerPeripheralExtension(extensionId: string, extension: unknown): void;
+
+    getScratchLinkSocket(type: 'BLE' | 'BT'): unknown;
+
+    configureScratchLinkSocketFactory(factory: (type: string) => unknown): void;
+
+    emitMicListening(listening: boolean): void;
+
     profiler: Profiler | null;
     enableProfiling(callback: (profilerFrame: ProfilerFrame) => void): void;
     disableProfiling(): void;
@@ -1376,7 +1579,7 @@ declare namespace VM {
     playgroundData: [{
       blocks: Blocks;
       // Stringified JSON of Thread[]
-      thread: string;
+      threads: string;
     }];
   }
 }
@@ -1527,13 +1730,13 @@ declare class VM extends EventEmitter<VM.VirtualMachineEventMap> {
    */
   addSprite(data: ArrayBufferView | ArrayBuffer | string | object): Promise<void>;
 
-  addCostume(md5ext: string, costume?: VM.Costume, targetId?: string, version?: 2): Promise<void>;
+  addCostume(md5ext: string, costume?: Partial<VM.Costume>, targetId?: string, version?: 2): Promise<void>;
 
-  addCostumeFromLibrary(md5ext: string, costume: VM.Costume): Promise<void>;
+  addCostumeFromLibrary(md5ext: string, costume: Partial<VM.Costume>): Promise<void>;
 
   addBackdrop(md5ext: string, costume?: VM.Costume): Promise<void>;
 
-  addSound(sound: VM.Sound, targetId?: string): Promise<void>;
+  addSound(sound: Partial<VM.Sound>, targetId?: string): Promise<void>;
 
   duplicateSprite(targetId: string): Promise<void>;
 
@@ -1656,4 +1859,50 @@ declare class VM extends EventEmitter<VM.VirtualMachineEventMap> {
    * @see {VM.Runtime.getPeripheralIsConnected}
    */
   getPeripheralIsConnected(extensionID: string): boolean;
+
+  /**
+   * Get data for playground. Data comes back in an emitted playgroundData event.
+   */
+  getPlaygroundData(): void;
+
+  /**
+   * Set the current locale and builtin messages for the VM. Resolves once all blocks have
+   * been updated for the new locale.
+   */
+  setLocale(locale: string, messages: Record<string, string>): Promise<void[]>;
+
+  /**
+   * Get the current locale for the VM.
+   */
+  getLocale(): string;
+
+  /**
+   * Delete all of the flyout blocks.
+   */
+  clearFlyoutBlocks(): void;
+
+  /**
+   * Handle a Blockly event for the current editing target.
+   */
+  blockListener(e: unknown): void;
+
+  /**
+   * Handle a Blockly event for the flyout.
+   */
+  flyoutBlockListener(e: unknown): void;
+
+  /**
+   * Handle a Blockly event for the flyout to be passed to the monitor container.
+   */
+  monitorBlockListener(e: unknown): void;
+
+  /**
+   * Handle a Blockly event for the variable map.
+   */
+  variableListener(e: unknown): void;
+
+  /**
+   * Allow VM consumer to configure the ScratchLink socket creator.
+   */
+  configureScratchLinkSocketFactory(factory: Function): void;
 }

package/types/twgl.d.ts

@@ -3,14 +3,23 @@
 
 declare namespace twgl {
   interface BufferInfo {
-    // TODO: returned by createBufferInfoFromArrays
-    // might not be able to meaningfully type?
+    numElements: number;
+    attribs: Record<string, {
+      buffer: WebGLBuffer;
+    }>;
   }
 
   interface ProgramInfo {
     // TODO: returned by createProgramInfo
   }
 
+  interface FrameBufferInfo {
+    attachments: WebGLTexture[];
+    framebuffer: WebGLFramebuffer;
+    width: number;
+    height: number;
+  }
+
   interface M4 {
     // TODO
   }
@@ -19,3 +28,14 @@ declare namespace twgl {
     // TODO
   }
 }
+
+declare class twgl {
+  createFramebufferInfo(...args: unknown[]): twgl.FrameBufferInfo;
+  resizeFramebufferInfo(...args: unknown[]): void;
+  createProgramInfo(...args: unknown[]): twgl.ProgramInfo;
+  createBufferInfoFromArrays(...args: unknown[]): twgl.BufferInfo;
+  createTexture(...args: unknown[]): WebGLTexture;
+  setBuffersAndAttributes(...args: unknown[]): void;
+  setUniforms(...args: unknown[]): void;
+  drawBufferInfo(...args: unknown[]): void;
+}

package/.github/workflows/deploy.yml

@@ -1,44 +0,0 @@
-name: Deploy documentation to GitHub Pages
-
-on:
-  workflow_dispatch:
-  push:
-    branches: [master]
-
-concurrency:
-  group: "deploy"
-  cancel-in-progress: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - name: Install Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-      - name: Install dependencies
-        run: npm ci
-      - name: Build documentation
-        run: npm run build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: ./docs/
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    permissions:
-      pages: write
-      id-token: write
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

package/.github/workflows/publish.yml

@@ -1,22 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  id-token: write
-  contents: read
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24
-      - run: npm ci
-      - run: npm test
-      - run: npm publish

package/.github/workflows/validate.yml

@@ -1,25 +0,0 @@
-name: Validate TypeScript
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-      - name: Install dependencies
-        run: npm ci
-      - name: Validate TypeScript
-        run: npm test
-      - name: Validate individual .d.ts files
-        run: |
-          parallel -v npx tsc --target es6 --noEmit ::: index.d.ts types/*.d.ts

package/CONTRIBUTING.md

@@ -1,9 +0,0 @@
-# Contributing
-
-Our goal is to document all the APIs exposed by Scratch. We accept any contributions that work towards that goal.
-
-Even if you aren't able to write types, please open issues to report missing or incorrect types.
-
-In terms of code style, we aren't super picky. Just keep it consistent with whatever is already there.
-
-For very complex types, please add a small test case in the `tests` directory. Presumably you already wrote some test code while writing the types, so just don't delete that once you're done.

package/tests/test-blockly.ts

@@ -1,15 +0,0 @@
-declare const RealBlockly: ScratchBlocks.RealBlockly;
-
-if (typeof Blockly === 'undefined') {
-  throw new Error('blockly doesnt exist')
-}
-
-const workspace = Blockly.getMainWorkspace();
-if (!workspace) {
-  throw new Error('no workspace');
-}
-
-workspace.id.toString();
-
-const fakeWorkspace = new RealBlockly.Workspace({});
-fakeWorkspace.id.charAt(0);

package/tests/test-cjs-es6.js

@@ -1,4 +0,0 @@
-import VM from 'scratch-vm';
-
-const vm = new VM();
-vm.clear();

package/tests/test-cjs-js.js

@@ -1,3 +0,0 @@
-const VirtualMachine = require('scratch-vm');
-const vm = new VirtualMachine();
-vm.clear();

package/tests/test-deprecated.js

@@ -1,4 +0,0 @@
-import VM from 'scratch-vm';
-const vm = new VM();
-// Your editor probably makes it clear that fromJSON is deprecated below
-vm.fromJSON(new ArrayBuffer(10));

package/tests/test-events.ts

@@ -1,15 +0,0 @@
-import VM from 'scratch-vm';
-
-const vm = new VM();
-const callback = (i: unknown) => console.log(i);
-
-vm.on('VISUAL_REPORT', callback);
-vm.off('VISUAL_REPORT', callback);
-vm.listeners('VISUAL_REPORT').forEach((i) => i({
-  id: 'def',
-  value: 'xyz'
-}));
-vm.emit('VISUAL_REPORT', {
-  id: 'abc',
-  value: 'def'
-});

package/tests/test-jszip.ts

@@ -1,16 +0,0 @@
-declare const stream: JSZip.StreamHelper<'uint8array'>;
-
-stream.on('data', data => {
-    data as Uint8Array
-});
-stream.on('data', (data, metadata) => {
-    metadata.percent as number
-});
-
-stream.pause();
-stream.resume();
-
-// @ts-expect-error
-stream.on('whatever', () => {
-
-});

package/tests/test-scratch-audio.ts

@@ -1,25 +0,0 @@
-import AudioEngine from 'scratch-audio';
-
-declare const vm: VM;
-const audioEngine = new AudioEngine();
-vm.attachAudioEngine(audioEngine);
-
-audioEngine.decodeSoundPlayer({
-  data: {
-    buffer: new ArrayBuffer(10)
-  }
-})
-  .then((player) => {
-    player.on('stop', () => {
-
-    });
-    return player.finished();
-  });
-
-declare const pitchEffect: AudioEngine.PitchEffect;
-pitchEffect.ratio as number
-pitchEffect.updatePlayers([]);
-
-declare const soundPlayer: AudioEngine.SoundPlayer;
-
-new audioEngine.effects[0](audioEngine, soundPlayer, pitchEffect);

package/tests/test-scratch-gui.ts

@@ -1,16 +0,0 @@
-declare const state: ScratchGUI.ReduxState;
-declare function dispatch(event: ScratchGUI.ReduxEvent): void;
-
-const vm = state.scratchGui.vm;
-vm.greenFlag();
-vm.renderer._allDrawables[0].updateVisible(false);
-
-dispatch({
-  type: 'scratch-gui/navigation/ACTIVATE_TAB',
-  activeTabIndex: 0
-});
-
-state.scratchPaint.cursor.charAt(0);
-dispatch({
-  type: 'scratch-paint/undo/CLEAR'
-});

package/tests/test-scratch-parser.ts

@@ -1,9 +0,0 @@
-import unpack from 'scratch-parser';
-
-unpack('{}', false, (error, unpacked) => {
-  if (error) {
-    console.error(error);
-  } else {
-    const [target, zip] = unpacked;
-  }
-});

package/tests/test-scratch-render-fonts.ts

@@ -1,4 +0,0 @@
-import getFonts from 'scratch-render-fonts';
-
-const fonts = getFonts();
-console.log(atob(fonts['Curly']));

package/tests/test-scratch-render.ts

@@ -1,8 +0,0 @@
-const canvas = document.createElement('canvas');
-const renderer = new RenderWebGL(canvas, 100, 200, 100, 200);
-
-// updateDrawableProperties should be deprecated
-renderer.updateDrawableProperties(10, {
-  whirl: 10,
-  position: [20, 30]
-});

package/tests/test-scratch-storage.ts

@@ -1,37 +0,0 @@
-import ScratchStorage from 'scratch-storage';
-
-declare const vm: VM;
-
-const storage = new ScratchStorage();
-vm.attachStorage(storage);
-
-ScratchStorage.DataFormat.JPG === 'jpg';
-storage.DataFormat.JPG === 'jpg';
-
-storage.addWebStore(
-  [
-    ScratchStorage.AssetType.ImageVector,
-    ScratchStorage.AssetType.ImageBitmap,
-    storage.AssetType.Sound,
-  ],
-  asset => {
-    const assetId = asset.assetId;
-    const dataFormat = asset.dataFormat;
-    return `https://assets.scratch.mit.edu/${assetId}.${dataFormat}`;
-  }
-);
-
-storage.createAsset(
-  storage.AssetType.ImageBitmap,
-  storage.DataFormat.PNG,
-  new Uint8Array([]),
-  null,
-  true
-) as ScratchStorage.Asset;
-storage.createAsset(
-  storage.AssetType.ImageBitmap,
-  storage.DataFormat.PNG,
-  new Uint8Array([]),
-  "1234567",
-  false
-) as ScratchStorage.Asset;

package/tests/test-scratch-svg-renderer.ts

@@ -1,8 +0,0 @@
-import * as SvgRenderer from 'scratch-svg-renderer';
-
-const svg = SvgRenderer.loadSvgString('imagine that this is an SVG', false);
-const serialized = SvgRenderer.serializeSvgToString(svg);
-const inlinedFonts = SvgRenderer.inlineSvgFonts('an svg here');
-const fixedFonts = SvgRenderer.convertFonts(SvgRenderer.SvgElement.create('svg'));
-
-const bitmapAdapter = new SvgRenderer.BitmapAdapter();

package/tests/test-scratch-vm-extension.js

@@ -1,105 +0,0 @@
-(function(Scratch) {
-  'use strict';
-
-  class Fetch {
-    /** @returns {Scratch.Info} */
-    getInfo () {
-      return {
-        id: 'fetch',
-        name: 'Fetch',
-        blocks: [
-          {
-            opcode: 'get',
-            blockType: Scratch.BlockType.REPORTER,
-            text: 'GET [URL]',
-            arguments: {
-              URL: {
-                type: Scratch.ArgumentType.STRING,
-                defaultValue: 'https://extensions.turbowarp.org/hello.txt'
-              }
-            }
-          },
-          '---',
-          {
-            opcode: 'test',
-            text: 'test [STRING] [IMAGE] [BOOLEAN] [NUMBER] [MATRIX] [NOTE] [ANGLE] [COLOR]',
-            blockType: Scratch.BlockType.COMMAND,
-            hideFromPalette: false,
-            isTerminal: true,
-            arguments: {
-              STRING: {
-                type: Scratch.ArgumentType.STRING,
-                defaultValue: 'test',
-                menu: 'test1'
-              },
-              IMAGE: {
-                type: Scratch.ArgumentType.IMAGE,
-                dataURI: 'https://extensions.turbowarp.org/dango.png'
-              },
-              BOOLEAN: {
-                type: Scratch.ArgumentType.BOOLEAN
-              },
-              NUMBER: {
-                type: Scratch.ArgumentType.NUMBER,
-                defaultValue: 5,
-              },
-              MATRIX: {
-                type: Scratch.ArgumentType.MATRIX,
-                defaultValue: '0101001010000001000101110'
-              },
-              NOTE: {
-                type: Scratch.ArgumentType.NOTE,
-                defaultValue: '30'
-              },
-              ANGLE: {
-                type: Scratch.ArgumentType.ANGLE,
-                defaultValue: 30
-              },
-              COLOR: {
-                type: Scratch.ArgumentType.COLOR,
-                defaultValue: '#123456'
-              }
-            }
-          },
-          {
-            blockType: Scratch.BlockType.BUTTON,
-            func: 'MAKE_A_VARIABLE',
-            text: 'button text'
-          }
-        ],
-        menus: {
-          test1: ['1', '2', '3'],
-          test2: {
-            acceptReporters: false,
-            items: [
-              { text: 'text', value: 'value' },
-              'another value'
-            ]
-          }
-        }
-      };
-    }
-
-    /**
-     * @param {{URL: string;}} args
-     */
-    get (args) {
-      return fetch(args.URL)
-        .then(r => r.text())
-        .catch(() => '');
-    }
-
-    /**
-     * @param {unknown} args
-     */
-    test (args) {
-      console.log(args);
-    }
-  }
-
-  if (Scratch.extensions.unsandboxed) {
-    // ...
-  }
-
-  Scratch.extensions.register(new Fetch());
-})(Scratch);

package/tests/test-scratch-vm.ts

@@ -1,84 +0,0 @@
-import VM from 'scratch-vm';
-import AudioEngine from 'scratch-audio';
-
-const vm = new VM();
-const runtime = vm.runtime;
-
-runtime.on('SCRIPT_GLOW_ON', (glowData) => {
-  const id: string = glowData.id;
-});
-vm.on('SCRIPT_GLOW_OFF', (glowData) => {
-  const id: string = glowData.id;
-});
-
-vm.emit('targetsUpdate', {
-  targetList: [],
-  editingTarget: 'abc 123'
-});
-
-const target = vm.runtime.getSpriteTargetByName('Sprite1');
-if (target) {
-  const variable = target.lookupVariableByNameAndType('test', 'list');
-  if (variable) {
-    const name: string = variable.name;
-    const upToDate: boolean | undefined = variable._monitorUpToDate;
-    variable.value.filter(i => i.toString());
-  }
-
-  target.lookupOrCreateVariable(')(!@*#)!(@#*()', 'my variable').value;
-
-  // @ts-expect-error
-  target.lookupVariableById('#@)$(*%)(#').id;
-
-  target.effects.ghost += 10;
-
-  const block = target.blocks.getBlock('123');
-  if (!block) {
-    throw new Error('no block :(');
-  }
-  if (block.opcode === 'procedures_call') {
-    const mutation = block.mutation as VM.ProcedureCallMutation;
-    JSON.parse(mutation.argumentids);
-  }
-
-  const bubbleState = target.getCustomState('Scratch.looks');
-  if (bubbleState) {
-    bubbleState.text.charAt(0);
-    target.setCustomState('Scratch.looks', bubbleState);
-  }
-
-  target.on('TARGET_MOVED', (target, fromX, fromY, forced) => {
-    const id: string = target.id;
-    const x: number = fromX;
-    const y: number = fromY;
-    const f: boolean | undefined = forced;
-  })
-  target.on('EVENT_TARGET_VISUAL_CHANGE', (target) => {
-    const id: string = target.id;
-  });
-
-  runtime.on('STOP_FOR_TARGET', (t: VM.RenderedTarget) => {
-
-  });
-} else {
-  const doesNotExist: undefined = target;
-}
-
-runtime._editingTarget as VM.Target;
-runtime.getEditingTarget() as VM.Target;
-
-const audioEngine = new AudioEngine();
-vm.attachAudioEngine(audioEngine);
-audioEngine.audioContext.suspend();
-
-vm.setTurboMode(true);
-vm.runtime.turboMode as boolean
-vm.setCompatibilityMode(true);
-vm.runtime.compatibilityMode as boolean
-
-const costume = vm.runtime.getTargetForStage()?.getCostumes()?.[0];
-costume?.skinId as number;
-
-declare const util: VM.BlockUtility;
-util.startHats('hats', {BROADCAST_OPTION: 'test'}) as VM.Thread[];
-util.ioQuery('mouse', 'getIsDown', []);

package/tests/test-scratchx-extension.js

@@ -1,29 +0,0 @@
-(function () {
-  const ext = {};
-
-  ext._getStatus = () => ({
-    status: 2,
-    msg: 'Ready'
-  });
-
-  ext.testReporter = () => Math.random();
-
-  /**
-   * @param {number} delay
-   * @param {function} callback
-   */
-  ext.testReporterWait = (delay, callback) => {
-    setTimeout(() => {
-      callback(Math.random())
-    }, delay * 1000);
-  };
-
-  var descriptor = {
-    blocks: [
-      ['r', 'test reporter', 'testReporter'],
-      ['R', 'test reporter 2 %n', 'testReporterWait', '1'],
-    ],
-  };
-  
-  ScratchExtensions.register('ScratchX Test', descriptor, ext);
-}());

package/tests/test-ts-es6.ts

@@ -1,4 +0,0 @@
-import VM from 'scratch-vm';
-
-const vm = new VM();
-vm.clear();

package/tests/test-ts-require.ts

@@ -1,4 +0,0 @@
-import VM = require('scratch-vm');
-
-const vm = new VM();
-vm.clear();