sb3-types 0.1.9

package/.github/workflows/jsr.yml

@@ -0,0 +1,19 @@
+name: Publish
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Publish package
+        run: npx jsr publish

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pnsk-lab
+
+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

@@ -0,0 +1,4 @@
+# sb3-type
+TypeScript definition for `project.json` of .sb3
+
+

package/biome.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.1/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "indentWidth": 2,
+    "indentStyle": "space"
+  },
+  "javascript": {
+    "formatter": {
+      "semicolons": "asNeeded",
+      "quoteStyle": "single"
+    }
+  }
+}

package/enum.ts

@@ -0,0 +1 @@
+export { Shadow, InputType } from './enums'

package/enums/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @module
+ * re-export the enums
+ */
+/**
+ * Shadow type indicating the appearance of the shadow.
+ */
+export * as Shadow from './shadow'
+
+/**
+ * enum of InputType
+ */
+export * as InputType from './inputtype'

package/enums/inputtype.ts

@@ -0,0 +1,58 @@
+/**
+ * @module
+ * Primitive type identifiers.
+ */
+/** When accepting all numbers */
+export type Number = 4
+// 汚染されるのはこのモジュールだけなので問題なし
+// biome-ignore lint/suspicious/noShadowRestrictedNames: <explanation>
+export const Number: Number = 4
+/** When accepting all positive numbers */
+export type PossiveNumber = 5
+export const PossiveNumber: PossiveNumber = 5
+/** When accepting all positive integers */
+export type PossiveInteger = 6
+export const PossiveInteger: PossiveInteger = 6
+/** When accepting all integers */
+export type Integer = 7
+export const Integer: Integer = 7
+/**
+ * A wheel from -180 to 180 is displayed when editing the value.
+ */
+export type Angle = 8
+export const Angle: Angle = 8
+/**
+ * Color picker appears when editing value.
+ * @example "#rrggbb"
+ */
+export type Color = 9
+export const Color: Color = 9
+/** When accepting all strings (and numbers) */
+export type String = 10
+// biome-ignore lint/suspicious/noShadowRestrictedNames: <explanation>
+export const String: String = 10
+/**  It is a message. */
+export type Broadcast = 11
+export const Broadcast: Broadcast = 11
+/**
+ * It is a round variable block.
+ */
+export type Variable = 12
+export const Variable: Variable = 12
+/**
+ * It is a round list block.
+ */
+export type List = 13
+export const List: List = 13
+/** Primitive type identifiers. */
+export type All =
+  | Number
+  | PossiveNumber
+  | PossiveInteger
+  | Integer
+  | Angle
+  | Color
+  | String
+  | Broadcast
+  | Variable
+  | List

package/enums/shadow.ts

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * Shadow type indicating the appearance of the shadow.
+ */
+/** unobscured shadow */
+export type UnObscured = 1
+export const UnObscured: UnObscured = 1
+/** no shadow */
+export type No = 2
+export const No: No = 2
+/** obscured shadow */
+export type Obscured = 3
+export const Obscured: Obscured = 3
+/**
+ * Shadow type indicating the appearance of the shadow.
+ */
+export type All = UnObscured | No | Obscured

package/jsr.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://jsr.io/schema/config-file.v1.json",
+  "name": "@pnsk-lab/sb3-types",
+  "exports": {
+    ".": "./mod.ts",
+    "./enum": "./enum.ts"
+  },
+  "version": "0.1.9",
+  "publish": {
+    "include": [
+      "package.json",
+      "README.md",
+      "**/*.ts"
+    ]
+  }
+}

package/mod.ts

@@ -0,0 +1,469 @@
+/**
+ * @module
+ * @example
+ * ```ts
+ * import type { ScratchProject } from '@pnsk-lab/sb3-types'
+ */
+
+import type { Shadow } from './enums/index.ts'
+import type { InputPrimitive, TopLevelPrimitive } from './primitive.ts'
+
+/**
+ * Scratch 3.0 Project Schema
+ */
+export interface ScratchProject {
+  meta: Meta
+  targets: (Stage | Sprite)[]
+}
+
+/**
+ * Metadata for the Scratch Project
+ */
+export interface Meta {
+  /**
+   * Semantic versioning of the project
+   * @pattern ^(3\.[0-9]+\.[0-9]+)$
+   */
+  semver: string
+
+  /**
+   * Version of the Scratch Virtual Machine
+   * @pattern ^([0-9]+\.[0-9]+\.[0-9]+)($|-)
+   */
+  vm?: string
+
+  /**
+   * Agent used for creating the project
+   */
+  agent?: string
+
+  /**
+   * Origin of the project
+   */
+  origin?: string
+}
+
+/**
+ * Stage type, representing the backdrop and stage-specific properties
+ */
+export interface Stage extends Target {
+  /**
+   * Name of the stage
+   */
+  name: 'Stage'
+
+  /**
+   * Indicates that this target is a stage
+   */
+  isStage: true
+
+  /**
+   * Tempo of the stage
+   */
+  tempo?: number
+
+  /**
+   * Transparency level of the video
+   */
+  videoTransparency?: number
+
+  /**
+   * State of the video
+   */
+  videoState?: 'on' | 'off' | 'on-flipped'
+
+  /**
+   * Layer order of the stage
+   */
+  layerOrder?: 0
+}
+
+/**
+ * Sprite type, representing the individual characters in the project
+ */
+export interface Sprite extends Target {
+  /**
+   * Name of the sprite
+   * @not "\_stage\_"
+   */
+  name: string
+
+  /**
+   * Indicates that this target is not a stage
+   */
+  isStage: false
+
+  /**
+   * Visibility of the sprite
+   */
+  visible?: boolean
+
+  /**
+   * X position of the sprite
+   */
+  x?: number
+
+  /**
+   * Y position of the sprite
+   */
+  y?: number
+
+  /**
+   * Size of the sprite
+   */
+  size?: number
+
+  /**
+   * Direction the sprite is facing
+   */
+  direction?: number
+
+  /**
+   * Whether the sprite is draggable
+   */
+  draggable?: boolean
+
+  /**
+   * Rotation style of the sprite
+   */
+  rotationStyle?: 'all around' | "don't rotate" | 'left-right'
+
+  /**
+   * Layer order of the sprite
+   * @minimum 1
+   */
+  layerOrder?: number
+}
+
+/**
+ * Common properties for both stages and sprites
+ */
+export interface Target {
+  /**
+   * Index of the current costume
+   * @minimum 0
+   */
+  currentCostume: number
+
+  /**
+   * Blocks associated with this target
+   */
+  blocks: { [id: string]: Block | TopLevelPrimitive }
+
+  /**
+   * Variables associated with this target
+   */
+  variables: { [id: string]: ScalarVariable }
+
+  /**
+   * Lists associated with this target
+   */
+  lists: { [id: string]: List }
+
+  /**
+   * Broadcast messages associated with this target
+   */
+  broadcasts: { [id: string]: string }
+
+  /**
+   * Comments associated with this target
+   */
+  comments?: { [id: string]: Comment }
+
+  /**
+   * Costumes associated with this target
+   */
+  costumes: Costume[]
+
+  /**
+   * Sounds associated with this target
+   */
+  sounds: Sound[]
+
+  /**
+   * Volume of the target
+   */
+  volume?: number
+}
+
+/**
+ * Definition for a block
+ * @see https://en.scratch-wiki.info/wiki/Scratch_File_Format#Blocks
+ */
+export interface Block {
+  /**
+   * A string naming the block.
+   */
+  opcode: string
+
+  /**
+   * Comment associated with the block
+   */
+  comment?: string
+  /**
+   * An object associating names with arrays representing inputs into which other blocks may be dropped, including C mouths.
+   * The first element of each array is 1 if the input is a shadow, 2 if there is no shadow, and 3 if there is a shadow but it is obscured by the input.
+   * The second is either the ID of the input or an array representing it as described in the table below.
+   * If there is an obscured shadow, the third element is its ID or an array representing it.
+   * @related {@link Input}
+   */
+  inputs?: { [id: string]: Input }
+
+  /**
+   * Fields are text boxes, drop-down menus, etc.
+   * These are used directly in {@link https://en.scratch-wiki.info/wiki/Blocks blocks} where there is an {@link https://en.scratch-wiki.info/wiki/Argument input} into which one cannot drop a {@link https://en.scratch-wiki.info/wiki/Reporter_Block reporter}.
+   * However, more often than not, one should be able to do this;
+   * in this case no field exists directly in the block, but an input does, and that input may have a shadow block in it.
+
+   * An object associating names with arrays representing fields.
+   * The first element of each array is the field's value.
+   * For certain fields, such as variable and broadcast dropdown menus, there is also a second element, which is the ID of the field's value.
+   * @example ```json
+   * { "KEY_OPTION": ["enter", null] }
+   * { "VARIABLE": ["variable_name", "variable_id"] }
+   * ```
+   */
+  fields?: {
+    [id: string]: Fields
+  }
+
+  /**
+   * The ID of the following block or `null`.
+   */
+  next?: string | null
+
+  /**
+   * False if the block has a parent and true otherwise.
+   */
+  topLevel?: boolean
+
+  /**
+   * If the block is a {@link https://en.scratch-wiki.info/wiki/Stack_Block stack block} and is preceded, this is the ID of the preceding block.
+   * If the block is the first stack block in a {@link https://en.scratch-wiki.info/wiki/C_Block C mouth}, this is the ID of the C block.
+   * If the block is an input to another block, this is the ID of that other block.
+   * Otherwise it is `null`.
+   */
+  parent?: string | null
+
+  /**
+   * True if this is a shadow block and false otherwise.
+   */
+  shadow?: boolean
+
+  /**
+   * X position of the block
+   */
+  x?: number
+
+  /**
+   * Y position of the block
+   */
+  y?: number
+
+  /**
+   * Mutation data for the block
+   */
+  mutation?: Mutation
+}
+
+/**
+ * look {@link Block.mutation}
+ */
+export type Mutation =
+  | Mutation_procedures_call
+  | Mutation_procedures_prototype
+  | Mutation_control_stop
+
+interface MutationBase {
+  /** The tag name, which is always 'mutation'. */
+  tagName?: 'mutation'
+
+  /** An array of child elements (typically empty). */
+  children?: []
+}
+
+interface Mutation_procedures_call extends MutationBase {
+  /** The procedure code for custom blocks. */
+  proccode?: string
+  /*
+   * https://github.com/scratchfoundation/scratch-parser/blob/665f05d739a202d565a4af70a201909393d456b2/lib/sb3_definitions.json#L282-L284
+   * ではstring
+   * https://en.scratch-wiki.info/wiki/Scratch_File_Format
+   * ではAn array of the ids of the argumentsとの記述。
+  /** The IDs of arguments for the procedure. */
+  argumentids?: string | string[]
+
+  /** Indicates if the procedure is a warp (runs without screen refresh). */
+  warp?: 'true' | 'false' | 'null' | boolean | null
+}
+interface Mutation_procedures_prototype extends MutationBase {
+  /**
+   * An array of the names of the arguments. This is only present when the block has an opcode of procedures_prototype.
+   */
+  argumentnames: string | string[]
+  /**
+   * An array of the defaults of the arguments; for string/number arguments, this is an empty string, and for boolean arguments it is false. This is only present when the block has an opcode of procedures_prototype.
+   */
+  argumentdefaults: (string | boolean)[]
+}
+interface Mutation_control_stop extends MutationBase {
+  /** Indicates if the procedure has a next block. */
+  hasnext?: 'true' | 'false' | 'null' | boolean | null
+}
+
+/**
+ * Definition for a comment
+ */
+export interface Comment {
+  /**
+   * ID of the block this comment is attached to
+   */
+  blockId?: string | null
+
+  /**
+   * Text of the comment
+   * @maxLength 8000
+   */
+  text: string
+
+  /**
+   * Indicates if the comment is minimized
+   */
+  minimized?: boolean
+
+  /**
+   * X position of the comment
+   */
+  x?: number | null
+
+  /**
+   * Y position of the comment
+   */
+  y?: number | null
+
+  /**
+   * Width of the comment
+   */
+  width?: number
+
+  /**
+   * Height of the comment
+   */
+  height?: number
+}
+
+/**
+ * Costume definition
+ */
+export interface Costume {
+  /**
+   * Asset ID of the costume
+   * @pattern ^[a-fA-F0-9]{32}$
+   */
+  assetId: string
+
+  /**
+   * Bitmap resolution of the costume
+   */
+  bitmapResolution?: number
+
+  /**
+   * Data format of the costume
+   * @enum ["png", "svg", "jpeg", "jpg", "bmp", "gif"]
+   */
+  dataFormat: 'png' | 'svg' | 'jpeg' | 'jpg' | 'bmp' | 'gif'
+
+  /**
+   * MD5 extension of the costume
+   * @pattern ^[a-fA-F0-9]{32}\.[a-zA-Z]+$
+   */
+  md5ext?: string
+
+  /**
+   * Name of the costume
+   */
+  name: string
+
+  /**
+   * X coordinate of the costume's rotation center
+   */
+  rotationCenterX?: number
+
+  /**
+   * Y coordinate of the costume's rotation center
+   */
+  rotationCenterY?: number
+}
+
+/**
+ * Sound definition
+ */
+export interface Sound {
+  /**
+   * Asset ID of the sound
+   * @pattern ^[a-fA-F0-9]{32}$
+   */
+  assetId: string
+
+  /**
+   * Data format of the sound
+   */
+  dataFormat: 'wav' | 'wave' | 'mp3'
+
+  /**
+   * MD5 extension of the sound
+   * @pattern ^[a-fA-F0-9]{32}\.[a-zA-Z0-9]+$
+   */
+  md5ext?: string
+
+  /**
+   * Name of the sound
+   */
+  name: string
+
+  /**
+   * Sample rate of the sound
+   */
+  rate?: number
+
+  /**
+   * Sample count of the sound
+   */
+  sampleCount?: number
+}
+
+/**
+ * Represents a scalar value, which can be a string, number, or boolean.
+ */
+export type ScalarVal = string | number | boolean
+
+/**
+ * Represents a scalar variable.
+ */
+export type ScalarVariable = [
+  displayName: string,
+  defaultValue: ScalarVal,
+  isCloudVariable?: boolean,
+]
+
+/**
+ * Represents a list.
+ */
+export type List = [displayName: string, defaultValue: ScalarVal[]]
+
+export type InputPrimitiveOrReference = InputPrimitive | /* blockId */ string
+
+/**
+ * The input value held by the block
+ * @related
+ */
+export type Input =
+  | [Shadow.UnObscured | Shadow.No, InputPrimitiveOrReference]
+  | [Shadow.Obscured, InputPrimitiveOrReference, InputPrimitiveOrReference]
+
+/**
+ * look {@link Block.fields}
+ */
+export type Fields = [string, null] | [string, string]
+
+export * from './primitive'

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "sb3-types",
+  "module": "index.ts",
+  "type": "module",
+  "version": "0.1.9",
+  "exports": {
+    ".": {
+      "default": "./dist/mod.mjs",
+      "types": "./dist/mod.d.ts"
+    },
+    "./enum": {
+      "default": "./dist/enums/index.mjs",
+      "types": "./dist/enums/index.d.ts"
+    }
+  },
+  "scripts": {
+    "publish": "jsr publish",
+    "format": "biome format",
+    "lint": "biome lint",
+    "format:fix": "biome format --fix"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.8.1",
+    "@types/bun": "latest",
+    "jsr": "^0.12.4",
+    "tsdown": "^0.20.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/primitive.ts

@@ -0,0 +1,103 @@
+import type { InputType } from './enums'
+
+/**
+ * Represents a number primitive in Scratch 3.0.
+ */
+
+export interface NumPrimitive {
+  /** Primitive type identifier. */
+  0:
+    | InputType.Number
+    | InputType.PossiveNumber
+    | InputType.PossiveInteger
+    | InputType.Integer
+    | InputType.Angle
+
+  /** The value of the number primitive, which can be a string or a number. */
+  1: string | number
+}
+
+/**
+ * Represents a color primitive in Scratch 3.0.
+ */
+export interface ColorPrimitive {
+  /** Primitive type identifier. */
+  0: InputType.Color
+
+  /** The color value in hex format (e.g., #RRGGBB). */
+  1: `#${string}`
+}
+
+/**
+ * Represents a text primitive in Scratch 3.0.
+ */
+export interface TextPrimitive {
+  /** Primitive type identifier. */
+  0: InputType.String
+
+  /** The value of the text primitive, which can be a string or a number. */
+  1: string | number
+} /**
+ * Represents a broadcast primitive in Scratch 3.0.
+ */
+export interface BroadcastPrimitive {
+  /** Primitive type identifier. */
+  0: InputType.Broadcast
+
+  /** The name of broadcast message. */
+  1: string
+
+  /** The broadcast message ID. */
+  2: string
+} /**
+ * Represents a variable primitive in Scratch 3.0.
+ */
+export interface VariablePrimitive {
+  /** Primitive type identifier. */
+  0: InputType.Variable
+
+  /** The name of the variable. */
+  1: string
+
+  /** The ID of the variable. */
+  2: string
+
+  /** x position */
+  3?: number
+
+  /** y position */
+  4?: number
+} /**
+ * Represents a list primitive in Scratch 3.0.
+ */
+export interface ListPrimitive {
+  /** Primitive type identifier. */
+  0: InputType.List
+
+  /** The name of the list. */
+  1: string
+
+  /** The ID of the list. */
+  2: string
+
+  /** x position */
+  3?: number
+
+  /** y position */
+  4?: number
+}
+/**
+ * Represents input primitives in Scratch 3.0.
+ */
+export type InputPrimitive =
+  | NumPrimitive
+  | ColorPrimitive
+  | TextPrimitive
+  | BroadcastPrimitive
+  | VariablePrimitive
+  | ListPrimitive
+/**
+ * Top-level primitive block
+ */
+
+export type TopLevelPrimitive = VariablePrimitive | ListPrimitive

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/tsdown.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["mod.ts", "enums/index.ts"],
+  dts: true,
+});