chore: add fish example

Author: mikebarkmin

README.md

@@ -27,13 +27,7 @@ A project file is a JSON object that configures the Blockflow editor. It is pass
   "title": "My Project",
   "sb3": "https://example.com/project.sb3",
   "ui": {
-    "allowExtensions": false,
-    "showCostumesTab": false,
-    "showSoundsTab": false,
-    "showBuiltinCostumes": false,
-    "showBuiltinSounds": false,
-    "showBuiltinBackdrops": false,
-    "showBuiltinSprites": false
+    "allowExtensions": false
   },
   "toolbox": {
     "categories": ["motion", "looks", "events", "control"],
@@ -53,27 +47,52 @@ A project file is a JSON object that configures the Blockflow editor. It is pass
       "image": "https://example.com/step2.png"
     }
   ],
-  "costumes": [
-    { "name": "Cat", "url": "https://example.com/cat.svg" },
-    { "name": "Photo", "url": "https://example.com/photo.png", "centerX": 100, "centerY": 80 }
-  ],
-  "sounds": [
-    { "name": "Meow", "url": "https://example.com/meow.mp3" }
-  ],
-  "backdrops": [
-    { "name": "Beach", "url": "https://example.com/beach.png" }
-  ],
-  "sprites": [
-    {
-      "name": "Dog",
-      "costumes": [
-        { "name": "dog-a", "url": "https://example.com/dog-a.svg" }
-      ],
-      "sounds": [
-        { "name": "bark", "url": "https://example.com/bark.mp3" }
-      ]
-    }
-  ]
+  "costumes": {
+    "enabled": false,
+    "showBuiltin": false,
+    "tags": [
+      { "key": "animal", "label": "Animal" },
+      { "key": "person", "label": "Person" }
+    ],
+    "library": [
+      { "name": "Cat", "url": "https://example.com/cat.svg", "tags": ["animal"] },
+      { "name": "Photo", "url": "https://example.com/photo.png", "centerX": 100, "centerY": 80, "tags": ["person"] }
+    ]
+  },
+  "sounds": {
+    "enabled": false,
+    "showBuiltin": false,
+    "tags": [
+      { "key": "effect", "label": "Effect" }
+    ],
+    "library": [
+      { "name": "Meow", "url": "https://example.com/meow.mp3", "tags": ["effect"] }
+    ]
+  },
+  "backdrops": {
+    "showBuiltin": false,
+    "library": [
+      { "name": "Beach", "url": "https://example.com/beach.png" }
+    ]
+  },
+  "sprites": {
+    "showBuiltin": false,
+    "tags": [
+      { "key": "animal", "label": "Animal" }
+    ],
+    "library": [
+      {
+        "name": "Dog",
+        "tags": ["animal"],
+        "costumes": [
+          { "name": "dog-a", "url": "https://example.com/dog-a.svg" }
+        ],
+        "sounds": [
+          { "name": "bark", "url": "https://example.com/bark.mp3" }
+        ]
+      }
+    ]
+  }
 }
 ```
 
@@ -82,19 +101,27 @@ A project file is a JSON object that configures the Blockflow editor. It is pass
 | `title` | **(required)** Project name displayed in the editor. |
 | `sb3` | URL to a `.sb3` file to load into the VM. |
 | `ui.allowExtensions` | Show or hide the extensions button. |
-| `ui.showCostumesTab` | Show or hide the Costumes/Backdrops tab. |
-| `ui.showSoundsTab` | Show or hide the Sounds tab. |
-| `ui.showBuiltinCostumes` | Show or hide built-in costumes in the costume library (default: `true`). |
-| `ui.showBuiltinSounds` | Show or hide built-in sounds in the sound library (default: `true`). |
-| `ui.showBuiltinBackdrops` | Show or hide built-in backdrops in the backdrop library (default: `true`). |
-| `ui.showBuiltinSprites` | Show or hide built-in sprites in the sprite library (default: `true`). |
 | `toolbox.categories` | Array of enabled block categories (`motion`, `looks`, `sound`, `events`, `control`, `sensing`, `operators`, `variables`, `myBlocks`). |
 | `toolbox.blocks` | Object mapping category names to arrays of allowed block opcodes for fine-grained filtering. |
 | `steps` | Array of tutorial steps, each with `title`, `text`, `image`, and/or `video`. |
-| `costumes` | Array of custom costumes, each with `name`, `url`, and optional `centerX`/`centerY` (default: center of image). Appear in the costume library. |
-| `sounds` | Array of custom sounds, each with `name` and `url`. Appear in the sound library. |
-| `backdrops` | Array of custom backdrops, each with `name`, `url`, and optional `centerX`/`centerY` (default: center of image). Appear in the backdrop library. |
-| `sprites` | Array of custom sprites, each with `name`, `costumes` (array), and `sounds` (array). Appear in the sprite library. |
+| `costumes` | Custom costumes. Can be a flat array of items (backward compatible) or an object with `enabled`, `showBuiltin`, `tags`, and `library`. |
+| `costumes.enabled` | Show or hide the Costumes/Backdrops tab (default: `true`). |
+| `costumes.showBuiltin` | Show or hide built-in costumes in the costume library (default: `true`). |
+| `costumes.tags` | Array of tag definitions (`{key, label}`) for filtering. Appended to built-in tags; shown alone when `showBuiltin` is `false`. |
+| `costumes.library` | Array of costume items, each with `name`, `url`, optional `centerX`/`centerY`, and optional `tags` (array of tag keys). |
+| `sounds` | Custom sounds. Can be a flat array or an object with `enabled`, `showBuiltin`, `tags`, and `library`. |
+| `sounds.enabled` | Show or hide the Sounds tab (default: `true`). |
+| `sounds.showBuiltin` | Show or hide built-in sounds in the sound library (default: `true`). |
+| `sounds.tags` | Array of tag definitions (`{key, label}`) for filtering. Appended to built-in tags; shown alone when `showBuiltin` is `false`. |
+| `sounds.library` | Array of sound items, each with `name`, `url`, and optional `tags` (array of tag keys). |
+| `backdrops` | Custom backdrops. Can be a flat array or an object with `showBuiltin`, `tags`, and `library`. |
+| `backdrops.showBuiltin` | Show or hide built-in backdrops in the backdrop library (default: `true`). |
+| `backdrops.tags` | Array of tag definitions (`{key, label}`) for filtering. Appended to built-in tags; shown alone when `showBuiltin` is `false`. |
+| `backdrops.library` | Array of backdrop items, each with `name`, `url`, optional `centerX`/`centerY`, and optional `tags` (array of tag keys). |
+| `sprites` | Custom sprites. Can be a flat array or an object with `showBuiltin`, `tags`, and `library`. |
+| `sprites.showBuiltin` | Show or hide built-in sprites in the sprite library (default: `true`). |
+| `sprites.tags` | Array of tag definitions (`{key, label}`) for filtering. Appended to built-in tags; shown alone when `showBuiltin` is `false`. |
+| `sprites.library` | Array of sprite items, each with `name`, `costumes`, `sounds`, and optional `tags` (array of tag keys). |
 
 Relative URLs in `sb3`, `image`, `video`, and asset `url` fields are resolved relative to the project file URL.
 

packages/scratch-gui/src/containers/backdrop-library.jsx

@@ -56,11 +56,18 @@ class BackdropLibrary extends React.Component {
     }
     render () {
         const mergedAssets = this.mergeDynamicAssets();
+        const {backdropTags: customBackdropTags, showBuiltinBackdrops} = this.props;
+        let tags = backdropTags;
+        if (showBuiltinBackdrops === false) {
+            tags = customBackdropTags || [];
+        } else if (customBackdropTags) {
+            tags = backdropTags.concat(customBackdropTags);
+        }
         return (
             <LibraryComponent
                 data={mergedAssets}
                 id="backdropLibrary"
-                tags={backdropTags}
+                tags={tags}
                 title={this.props.intl.formatMessage(messages.libraryTitle)}
                 onItemSelected={this.handleItemSelect}
                 onRequestClose={this.props.onRequestClose}
@@ -71,14 +78,28 @@ class BackdropLibrary extends React.Component {
 
 const mapStateToProps = state => {
     const projectFile = state.scratchGui.projectFile.projectFile;
+    const da = state.scratchGui.dynamicAssets;
+    let showBuiltinBackdrops;
+    if (da.showBuiltinBackdrops !== null) {
+        showBuiltinBackdrops = da.showBuiltinBackdrops;
+    } else if (projectFile && projectFile.ui) {
+        showBuiltinBackdrops = projectFile.ui.showBuiltinBackdrops;
+    }
     return {
-        dynamicBackdrops: state.scratchGui.dynamicAssets.backdrops,
-        showBuiltinBackdrops: projectFile && projectFile.ui ?
-            projectFile.ui.showBuiltinBackdrops : undefined
+        dynamicBackdrops: da.backdrops,
+        showBuiltinBackdrops,
+        backdropTags: da.backdropTags
     };
 };
 
 BackdropLibrary.propTypes = {
+    backdropTags: PropTypes.arrayOf(PropTypes.shape({
+        tag: PropTypes.string,
+        intlLabel: PropTypes.shape({
+            id: PropTypes.string,
+            defaultMessage: PropTypes.string
+        })
+    })),
     dynamicBackdrops: PropTypes.arrayOf(costumeShape),
     intl: intlShape.isRequired,
     onRequestClose: PropTypes.func,

packages/scratch-gui/src/containers/costume-library.jsx

@@ -55,11 +55,18 @@ class CostumeLibrary extends React.PureComponent {
     }
     render () {
         const data = this.mergeDynamicAssets();
+        const {costumeTags, showBuiltinCostumes} = this.props;
+        let tags = spriteTags;
+        if (showBuiltinCostumes === false) {
+            tags = costumeTags || [];
+        } else if (costumeTags) {
+            tags = spriteTags.concat(costumeTags);
+        }
         return (
             <LibraryComponent
                 data={data}
                 id="costumeLibrary"
-                tags={spriteTags}
+                tags={tags}
                 title={this.props.intl.formatMessage(messages.libraryTitle)}
                 onItemSelected={this.handleItemSelected}
                 onRequestClose={this.props.onRequestClose}
@@ -70,14 +77,28 @@ class CostumeLibrary extends React.PureComponent {
 
 const mapStateToProps = state => {
     const projectFile = state.scratchGui.projectFile.projectFile;
+    const da = state.scratchGui.dynamicAssets;
+    let showBuiltinCostumes;
+    if (da.showBuiltinCostumes !== null) {
+        showBuiltinCostumes = da.showBuiltinCostumes;
+    } else if (projectFile && projectFile.ui) {
+        showBuiltinCostumes = projectFile.ui.showBuiltinCostumes;
+    }
     return {
-        dynamicCostumes: state.scratchGui.dynamicAssets.costumes,
-        showBuiltinCostumes: projectFile && projectFile.ui ?
-            projectFile.ui.showBuiltinCostumes : undefined
+        dynamicCostumes: da.costumes,
+        costumeTags: da.costumeTags,
+        showBuiltinCostumes
     };
 };
 
 CostumeLibrary.propTypes = {
+    costumeTags: PropTypes.arrayOf(PropTypes.shape({
+        tag: PropTypes.string,
+        intlLabel: PropTypes.shape({
+            id: PropTypes.string,
+            defaultMessage: PropTypes.string
+        })
+    })),
     dynamicCostumes: PropTypes.arrayOf(costumeShape),
     intl: intlShape.isRequired,
     onRequestClose: PropTypes.func,

packages/scratch-gui/src/containers/sound-library.jsx

@@ -183,13 +183,21 @@ class SoundLibrary extends React.PureComponent {
             };
         });
 
+        const {soundTags: customSoundTags, showBuiltinSounds} = this.props;
+        let tags = soundTags;
+        if (showBuiltinSounds === false) {
+            tags = customSoundTags || [];
+        } else if (customSoundTags) {
+            tags = soundTags.concat(customSoundTags);
+        }
+
         return (
             <LibraryComponent
                 showPlayButton
                 data={soundLibraryThumbnailData}
                 id="soundLibrary"
                 setStopHandler={this.setStopHandler}
-                tags={soundTags}
+                tags={tags}
                 title={this.props.intl.formatMessage(messages.libraryTitle)}
                 onItemMouseEnter={this.handleItemMouseEnter}
                 onItemMouseLeave={this.handleItemMouseLeave}
@@ -207,16 +215,30 @@ SoundLibrary.propTypes = {
     onNewSound: PropTypes.func.isRequired,
     onRequestClose: PropTypes.func,
     showBuiltinSounds: PropTypes.bool,
+    soundTags: PropTypes.arrayOf(PropTypes.shape({
+        tag: PropTypes.string,
+        intlLabel: PropTypes.shape({
+            id: PropTypes.string,
+            defaultMessage: PropTypes.string
+        })
+    })),
     vm: PropTypes.instanceOf(VM).isRequired
 };
 
 const mapStateToProps = state => {
     const projectFile = state.scratchGui.projectFile.projectFile;
+    const da = state.scratchGui.dynamicAssets;
+    let showBuiltinSounds;
+    if (da.showBuiltinSounds !== null) {
+        showBuiltinSounds = da.showBuiltinSounds;
+    } else if (projectFile && projectFile.ui) {
+        showBuiltinSounds = projectFile.ui.showBuiltinSounds;
+    }
     return {
-        dynamicSounds: state.scratchGui.dynamicAssets.sounds,
+        dynamicSounds: da.sounds,
         isRtl: state.locales.isRtl,
-        showBuiltinSounds: projectFile && projectFile.ui ?
-            projectFile.ui.showBuiltinSounds : undefined
+        showBuiltinSounds,
+        soundTags: da.soundTags
     };
 };
 

packages/scratch-gui/src/containers/sprite-library.jsx

@@ -53,11 +53,18 @@ class SpriteLibrary extends React.PureComponent {
     }
     render () {
         const data = this.mergeDynamicAssets();
+        const {spriteTags: customSpriteTags, showBuiltinSprites} = this.props;
+        let tags = spriteTags;
+        if (showBuiltinSprites === false) {
+            tags = customSpriteTags || [];
+        } else if (customSpriteTags) {
+            tags = spriteTags.concat(customSpriteTags);
+        }
         return (
             <LibraryComponent
                 data={data}
                 id="spriteLibrary"
-                tags={spriteTags}
+                tags={tags}
                 title={this.props.intl.formatMessage(messages.libraryTitle)}
                 onItemSelected={this.handleItemSelect}
                 onRequestClose={this.props.onRequestClose}
@@ -68,10 +75,17 @@ class SpriteLibrary extends React.PureComponent {
 
 const mapStateToProps = state => {
     const projectFile = state.scratchGui.projectFile.projectFile;
+    const da = state.scratchGui.dynamicAssets;
+    let showBuiltinSprites;
+    if (da.showBuiltinSprites !== null) {
+        showBuiltinSprites = da.showBuiltinSprites;
+    } else if (projectFile && projectFile.ui) {
+        showBuiltinSprites = projectFile.ui.showBuiltinSprites;
+    }
     return {
-        dynamicSprites: state.scratchGui.dynamicAssets.sprites,
-        showBuiltinSprites: projectFile && projectFile.ui ?
-            projectFile.ui.showBuiltinSprites : undefined
+        dynamicSprites: da.sprites,
+        showBuiltinSprites,
+        spriteTags: da.spriteTags
     };
 };
 
@@ -81,6 +95,13 @@ SpriteLibrary.propTypes = {
     onActivateBlocksTab: PropTypes.func.isRequired,
     onRequestClose: PropTypes.func,
     showBuiltinSprites: PropTypes.bool,
+    spriteTags: PropTypes.arrayOf(PropTypes.shape({
+        tag: PropTypes.string,
+        intlLabel: PropTypes.shape({
+            id: PropTypes.string,
+            defaultMessage: PropTypes.string
+        })
+    })),
     vm: PropTypes.instanceOf(VM).isRequired
 };
 

packages/scratch-gui/src/lib/fetch-project-file.js

@@ -59,19 +59,38 @@ const fetchProjectFile = async function (url) {
         });
     };
 
-    projectFile.sounds = resolveAssetUrls(projectFile.sounds);
-    projectFile.costumes = resolveAssetUrls(projectFile.costumes);
-    projectFile.backdrops = resolveAssetUrls(projectFile.backdrops);
+    // Normalize an asset-type field that may be a flat array or {tags, library, showBuiltin}
+    const normalizeAssetField = field => {
+        if (!field) return field;
+        if (Array.isArray(field)) return resolveAssetUrls(field);
+        if (typeof field === 'object') {
+            const normalized = Object.assign({}, field);
+            if (Array.isArray(normalized.library)) {
+                normalized.library = resolveAssetUrls(normalized.library);
+            }
+            return normalized;
+        }
+        return field;
+    };
+
+    projectFile.sounds = normalizeAssetField(projectFile.sounds);
+    projectFile.costumes = normalizeAssetField(projectFile.costumes);
+    projectFile.backdrops = normalizeAssetField(projectFile.backdrops);
 
     // Resolve sprite asset URLs (nested costumes and sounds)
-    if (Array.isArray(projectFile.sprites)) {
-        projectFile.sprites = projectFile.sprites.map(sprite => {
-            const resolved = Object.assign({}, sprite);
-            resolved.costumes = resolveAssetUrls(resolved.costumes);
-            resolved.sounds = resolveAssetUrls(resolved.sounds);
-            return resolved;
+    const normalizeSprites = sprites => {
+        if (!sprites) return sprites;
+        const list = Array.isArray(sprites) ? sprites : (sprites.library || []);
+        const resolved = list.map(sprite => {
+            const s = Object.assign({}, sprite);
+            s.costumes = resolveAssetUrls(s.costumes);
+            s.sounds = resolveAssetUrls(s.sounds);
+            return s;
         });
-    }
+        if (Array.isArray(sprites)) return resolved;
+        return Object.assign({}, sprites, {library: resolved});
+    };
+    projectFile.sprites = normalizeSprites(projectFile.sprites);
 
     return projectFile;
 };