@turbowarp/types 0.0.13 → 0.0.15

package/types/scratch-vm.d.ts

@@ -41,9 +41,11 @@ declare namespace VM {
     assetId: string;
 
     /**
-     * The md5 + file extension of this asset.
+     * The md5 + file extension of this asset. May be missing.
      */
-    md5: string;
+    md5?: string;
+
+    md5ext?: string;
 
     name: string;
 
@@ -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(block: Block): Record<string, Field> | null;
 
-    getFields(id: string): object | null;
+    getInputs(block: Block): Record<string, Input> | null;
 
-    getInputs(id: string): object | 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;
@@ -740,19 +873,40 @@ declare namespace VM {
     // TODO
   }
 
-  interface Profiler {
-    // TODO
+  interface ProfilerFrame {
+    id: number;
+    totalTime: number;
+    selfTime: number;
+    arg: unknown;
+    depth: number;
+    count: number;
   }
 
-  interface ProfilerFrame {
-    // TODO
+  type FrameCallback = (frame: ProfilerFrame) => void;
+
+  interface Profiler {
+    records: unknown[];
+    increments: ProfilerFrame[];
+    counters: ProfilerFrame[];
+    nullFrame: ProfilerFrame;
+    _stack: ProfilerFrame[];
+    onFrame: FrameCallback;
+    START: 0;
+    STOP: 1;
+    start(id: number, arg: unknown): void;
+    stop(): void;
+    increment(id: number): void;
+    frame(id: number, arg: unknown): ProfilerFrame;
+    reportFrames(): void;
+    idByName(name: string): number;
+    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;
@@ -760,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[]>;
 
@@ -789,9 +944,9 @@ declare namespace VM {
   interface Timer {
     startTime: number;
 
-    time(): number;
+    nowObj: { now(): number };
 
-    relativeTime(): number;
+    time(): number;
 
     start(): void;
 
@@ -880,6 +1035,7 @@ declare namespace VM {
     canvasWidth?: number;
     canvasHeight?: number;
     isDown?: boolean;
+    wasDragged?: boolean;
   }
 
   interface Mouse {
@@ -923,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;
   }
 
@@ -1106,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;
@@ -1181,7 +1375,7 @@ declare namespace VM {
 
     _stopThread(thread: Thread): void;
 
-    _restartThread(thread: Thread): void;
+    _restartThread(thread: Thread): Thread;
 
     /**
      * A thread is considered active if it is in the thread list and is not STATUS_DONE.
@@ -1199,7 +1393,7 @@ declare namespace VM {
 
     _getMonitorThreadCount(threads: Thread[]): number;
 
-    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): Thread[];
+    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): Thread[] | undefined;
 
     toggleScript(topBlockId: string, options?: {
       target?: string;
@@ -1216,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>;
@@ -1232,6 +1442,8 @@ declare namespace VM {
       xml: string;
     }>;
 
+    getBlocksJSON(): object[];
+
     _blockInfo: ExtensionInfo[];
 
     _hats: Record<string, HatInfo>;
@@ -1318,6 +1530,8 @@ declare namespace VM {
 
     emitProjectLoaded(): void;
 
+    handleProjectLoaded(): void;
+
     emitProjectChanged(): void;
 
     _editingTarget: Target | null;
@@ -1333,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;
@@ -1355,7 +1579,7 @@ declare namespace VM {
     playgroundData: [{
       blocks: Blocks;
       // Stringified JSON of Thread[]
-      thread: string;
+      threads: string;
     }];
   }
 }
@@ -1506,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>;
 
@@ -1635,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,45 +0,0 @@
-name: Deploy playground
-
-on:
-  workflow_dispatch:
-  push:
-    branches: [master]
-
-concurrency:
-  group: "deploy"
-  cancel-in-progress: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with:
-          persist-credentials: false
-      - name: Install Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
-        with:
-          node-version: 20
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Build documentation
-        run: npm run build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa
-        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@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e

package/.github/workflows/validate.yml

@@ -1,26 +0,0 @@
-name: Validate TypeScript
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with:
-          persist-credentials: false
-      - name: Setup Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
-        with:
-          node-version: 20
-          cache: npm
-      - 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));