@turbowarp/types 0.0.5 → 0.0.6

package/README.md

@@ -2,9 +2,7 @@
 
 Scratch doesn't provide type definitions for their libraries, so we wrote our own.
 
-This project is still at an early stage.
-
-Despite being in the TurboWarp organization, this project is currently focused only on the vanilla (LLK) Scratch runtime and editor. Additional types for TurboWarp may be added later.
+This repository only contains types for the vanilla (LLK) Scratch runtime and editor. For the additional types in the TurboWarp runtimes, see [@turbowarp/types-tw](https://github.com/TurboWarp/types-tw).
 
 |Module|Status|
 |:-:|:-:|

package/package.json

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

package/tests/test-jszip.ts

@@ -0,0 +1,16 @@
+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-vm-extension.js

@@ -2,6 +2,7 @@
   'use strict';
 
   class Fetch {
+    /** @returns {Scratch.Info} */
     getInfo () {
       return {
         id: 'fetch',
@@ -17,8 +18,65 @@
                 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'
+              }
+            }
+          },
+          {
+            opcode: 'button',
+            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'
+            ]
           }
-        ]
+        }
       };
     }
 
@@ -30,6 +88,17 @@
         .then(r => r.text())
         .catch(() => '');
     }
+
+    /**
+     * @param {unknown} args
+     */
+    test (args) {
+      console.log(args);
+    }
+  }
+
+  if (Scratch.extensions.unsandboxed) {
+    // ...
   }
 
   Scratch.extensions.register(new Fetch());

package/tests/test-scratch-vm.ts

@@ -61,3 +61,7 @@ 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/types/jszip.d.ts

@@ -3,6 +3,30 @@
 
 declare namespace JSZip {
   // TODO
+
+  interface OutputTypes {
+    base64: string;
+    binarystring: string;
+    array: number[];
+    uint8array: Uint8Array;
+    arraybuffer: ArrayBuffer;
+    blob: Blob;
+    nodebuffer: Uint8Array; // actually a Node.js Buffer
+  }
+
+  interface ProgressMetadata {
+    percent: number;
+    currentFile: string;
+  }
+
+  interface StreamHelper<T extends keyof OutputTypes> {
+    resume(): void;
+    pause(): void;
+    on(event: 'data', callback: (data: OutputTypes[T], metadata: ProgressMetadata) => void): void;
+    on(event: 'end', callback: () => void): void;
+    on(event: 'error', callback: (error: Error) => void): void;
+    accumulate(updateCallback?: (metadata: ProgressMetadata) => void): Promise<OutputTypes[T]>;
+  }
 }
 
 declare class JSZip {

package/types/scratch-vm-extension.d.ts

@@ -1,133 +1,251 @@
-/// <reference path="./scratch-vm.d.ts" />
-/// <reference path="./scratch-render.d.ts" />
-
 declare namespace Scratch {
+  // Note that the 'B' in the BOOLEAN enums are capitalized in Scratch. It is not a typo in this file.
+
   namespace ArgumentType {
-    /** @deprecated not tested -- do not rely on yet */
     const ANGLE: 'angle';
     const BOOLEAN: 'Boolean';
-    /** @deprecated not tested -- do not rely on yet */
     const COLOR: 'color';
-    const NUMBER: 'number';
-    const STRING: 'string';
-    /** @deprecated not tested -- do not rely on yet */
+    const IMAGE: 'image';
     const MATRIX: 'matrix';
-    /** @deprecated not tested -- do not rely on yet */
     const NOTE: 'note';
-    /** @deprecated not tested -- do not rely on yet */
-    const IMAGE: 'image';
+    const NUMBER: 'number';
+    const STRING: 'string';
   }
-  type ArgumentType = (typeof ArgumentType)[keyof typeof ArgumentType];
-  
+
   namespace BlockType {
-    // The B in Boolean is supposed to be capitalized
     const BOOLEAN: 'Boolean';
-    /** @deprecated not tested -- do not rely on yet */
+    /** @deprecated very incomplete and not useful yet */
     const BUTTON: 'button';
     const COMMAND: 'command';
-    /** @deprecated not tested -- do not rely on yet */
+    /** @deprecated does not work in compiler */
     const CONDITIONAL: 'conditional';
+    /** @deprecated use HAT instead */
     const EVENT: 'event';
     const HAT: 'hat';
-    /** @deprecated not tested -- do not rely on yet */
+    /** @deprecated does not work in compiler */
     const LOOP: 'loop';
     const REPORTER: 'reporter';
   }
-  type BlockType = (typeof BlockType)[keyof typeof BlockType];
-  
+
   namespace TargetType {
     const SPRITE: 'sprite';
     const STAGE: 'stage';
   }
-  type TargetType = (typeof TargetType)[keyof typeof TargetType];
-  
-  /**
-   * scratch-vm instance. Only for unsandboxed extensions.
-   */
-  const vm: VM;
-  
-  /**
-   * scratch-render instance. Only for unsandboxed extensions.
-   */
-  const renderer: RenderWebGL;
-  
-  /**
-   * Technically this can be a translatable object, but in reality it will probably just be
-   * a string here.
-   */
-  type FormattableString = string;
-  
-  interface ExtensionArgumentInfo {
-    type: ArgumentType;
+
+  interface AngleArgument {
+    type: 'angle';
+    /**
+     * Defaults to 0.
+     */
+    defaultValue?: string | number;
+  }
+  interface BooleanArgument {
+    type: 'Boolean';
+  }
+  interface ColorArgument {
+    type: 'color';
+    /**
+     * Should be a hex color code. No alpha channel supported. Defaults to random color.
+     */
+    defaultValue?: string | number;
+  }
+  interface NumberArgument {
+    type: 'number';
+    /**
+     * Defaults to 0.
+     */
     defaultValue?: string | number;
     menu?: string;
   }
-  
-  interface ExtensionBlock {
+  interface StringArgument {
+    type: 'string';
+    /**
+     * Defaults to empty string.
+     */
+    defaultValue?: string | number;
+    menu?: string;
+  }
+  interface MatrixArgument {
+    type: 'matrix';
+    /**
+     * Should be a 25 character long string of 1s and 0s.
+     * Numbers are technically accepted, but be aware that due to floating point precision, some detail may be lost.
+     * Technically optional, but behaves strangely with no default value.
+     */
+    defaultValue?: string | number;
+  }
+  interface NoteArgument {
+    type: 'note';
+    /**
+     * Defaults to 0 ("C (0)")
+     */
+    defaultValue?: string | number;
+  }
+  interface ImageArgument {
+    type: 'image';
+    dataURI: string;
+    /**
+     * Defaults to false.
+     */
+    flipRTL?: boolean;
+  }
+  type Argument = (
+    AngleArgument |
+    BooleanArgument |
+    ColorArgument |
+    NumberArgument |
+    StringArgument |
+    MatrixArgument |
+    NoteArgument |
+    ImageArgument
+  );
+
+  interface AbstractBlock {
     opcode: string;
-    blockType: BlockType;
-    text: FormattableString;
-    arguments?: Record<string, ExtensionArgumentInfo>;
-    // TODO: documentation mentions func, filter, branchCount, terminal, blockAllThreads
+    func?: string;
+    text: string | string[];
+    arguments?: Record<string, Argument>;
+    hideFromPalette?: boolean;
+    filter?: Array<'target' | 'sprite'>;
+    blockIconURI?: string;
   }
-  
-  interface ExtensionMenu {
+  interface BooleanBlock extends AbstractBlock {
+    blockType: 'Boolean';
+  }
+  interface ButtonBlock extends AbstractBlock {
+    blockType: 'button';
+    func: 'MAKE_A_LIST' | 'MAKE_A_PROCEDURE' | 'MAKE_A_VARIABLE';
+  }
+  interface CommandBlock extends AbstractBlock {
+    blockType: 'command';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+  }
+  interface ConditionalBlock extends AbstractBlock {
+    blockType: 'conditional';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+    /**
+     * Defaults to 1.
+     */
+    branchCount?: number;
+  }
+  interface EventBlock extends AbstractBlock {
+    blockType: 'event';
+    /**
+     * This must be explicitly set to false, otherwise the block will not work.
+     * Event blocks cannot be edge activated. Use hat instead.
+     */
+    isEdgeActivated: false;
+    /**
+     * Defaults to false.
+     */
+    shouldRestartExistingThreads?: boolean;
+  }
+  interface HatBlock extends AbstractBlock {
+    blockType: 'hat';
+    /**
+     * Defaults to true.
+     */
+    isEdgeActivated?: boolean;
+    /**
+     * Defaults to false.
+     */
+    shouldRestartExistingThreads?: boolean;
+  }
+  interface ReporterBlock extends AbstractBlock {
+    blockType: 'reporter';
+    /**
+     * Defaults to false.
+     */
+    disableMonitor?: boolean;
+  }
+  interface LoopBlock extends AbstractBlock {
+    blockType: 'loop';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+    /**
+     * Defaults to 1.
+     */
+    branchCount?: number;
+  }
+  type Block = (
+    BooleanBlock |
+    ButtonBlock |
+    CommandBlock |
+    ConditionalBlock |
+    EventBlock |
+    HatBlock |
+    ReporterBlock |
+    LoopBlock
+  );
+
+  interface Menu {
     acceptReporters?: boolean;
+    /**
+     * A list of static items in the menu, or the name of the dynamic menu function.
+     */
     items: Array<string | {
       text: string;
       value: string;
-    }>;
+    }> | string;
   }
-  
-  interface ExtensionInfo {
+
+  interface Info {
     id: string;
-  
+
     /**
-     * Defaults to ID if not specified.
+     * Defaults to extension ID if not specified.
      */
-    name?: FormattableString;
-  
+    name?: string;
+
     /**
      * Should be a hex color code.
      */
     color1?: string;
-  
+
     /**
      * Should be a hex color code.
      */
     color2?: string;
-  
+
     /**
      * Should be a hex color code.
      */
     color3?: string;
-  
+
     /**
      * Should be a data: URI
      */
     menuIconURI?: string;
-  
+
     /**
      * Should be a data: URI
      */
     blockIconURI?: string;
-  
+
     docsURI?: string;
-  
-    blocks: (ExtensionBlock | string)[];
-    menus?: Record<string, ExtensionMenu>;
+
+    blocks: (Block | string)[];
+    menus?: Record<string, Menu | string[]>;
   }
-  
+
   interface Extension {
-    getInfo(): ExtensionInfo;
+    getInfo(): Info;
   }
-  
+
   namespace extensions {
     function register(extensionObject: Extension): void;
   
     /**
-     * True if the extension is running unsandboxed.
+     * True if the extension is running unsandboxed, otherwise undefined.
      */
-    const unsandboxed: boolean;
+    const unsandboxed: undefined | boolean;
   }
 }

package/types/scratch-vm.d.ts

@@ -614,7 +614,72 @@ declare namespace VM {
   }
 
   interface StackFrame {
-    // TODO
+    isLoop: boolean;
+    warpMode: boolean;
+    justReported: unknown;
+    reporting: string;
+    reported: unknown;
+    /** @deprecated unused */
+    waitingReporter: unknown;
+    params: unknown;
+    executionContext: unknown;
+    reset(): void;
+  }
+
+  interface BlockUtility {
+    sequencer: Sequencer;
+    thread: Thread;
+    _nowObj: {
+      now(): number;
+    };
+    nowObj: BlockUtility['_nowObj'],
+    target: Target;
+    runtime: Runtime;
+    stackFrame: StackFrame;
+    stackTimerFinished(): boolean;
+    stackTimerNeedsInit(): boolean;
+    startStackTimer(milliseconds: number): void;
+    yield(): void;
+    yieldTick(): void;
+    startBranch(branchNumber: number, isLoop: boolean): void;
+    /**
+     * @see {Runtime.stopAll}
+     */
+    stopAll(): void;
+    /**
+     * @see {Runtime.stopForTarget}
+     */
+    stopOtherTargetThreads(): void;
+    /**
+     * @see {Thread.stopThisScript}
+     */
+    stopThisScript(): void;
+    /**
+     * @see {Blocks.getProcedureParamNamesAndIds}
+     */
+    getProcedureParamNamesAndIds(): [string[], string[]];
+    /**
+     * @see {Blocks.getProcedureParamNamesIdsAndDefaults}
+     */
+    getProcedureParamNamesIdsAndDefaults(): [string[], string[], string[]];
+    /**
+     * @see {Thread.initParams}
+     */
+    initParams(): void;
+    /**
+     * @see {Thread.pushParam}
+     */
+    pushParam(name: string, value: ScratchCompatibleValue): void;
+    /**
+     * @see {Thread.getParam}
+     */
+    getParam(name: string): ScratchCompatibleValue;
+    /**
+     * Use instead of runtime.startHats inside blocks.
+     * @see {Runtime.startHats}
+     */
+    startHats: Runtime['startHats'];
+    ioQuery<Device extends keyof IODevices>(device: Device, func: keyof IODevices[Device], args: unknown[]): unknown;
   }
 
   const enum ThreadStatus {
@@ -637,16 +702,19 @@ declare namespace VM {
     blockGlowInFrame: string | null;
     warpTimer: Timer | null;
     justReported: unknown;
+    reuseStackForNextBlock(blockId: string): void;
     pushStack(blockId: string): void;
     popStack(): string;
     peekStack(): string;
     peekStackFrame(): StackFrame | null;
     peekParentStackFrame(): StackFrame | null;
+    pushReportedValue(value: ScratchCompatibleValue): void;
     initParams(): void;
     pushParam(name: string, value: ScratchCompatibleValue): void;
     getParam(name: string): ScratchCompatibleValue | null;
     atStackTop(): boolean;
     goToNextBlock(): void;
+    stopThisScript(): void;
     isRecursiveCall(procedureCode: string): boolean;
     stackClick: boolean;
     updateMonitor: boolean;
@@ -1117,7 +1185,7 @@ declare namespace VM {
 
     _getMonitorThreadCount(threads: Thread[]): number;
 
-    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): void;
+    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): Thread[];
 
     toggleScript(topBlockId: string, options?: {
       target?: string;