@eventcatalog/core 4.3.2 → 4.3.4

package/dist/docs/plugins/asyncapi/03-features.md

@@ -15,7 +15,7 @@ import TabItem from '@theme/TabItem';
 | Feature | Use cases |
 |---------|-----------|
 | [Mapping messages events, commands or queries](#mapping-messages-events-commands-or-queries) | AsyncAPI does not distinguish between commands, events and queries, everything is a message. Using the EventCatalog custom AsyncAPI [extension](https://www.asyncapi.com/docs/concepts/asyncapi-document/extending-specification) `x-eventcatalog-message-type` you can specify if your messages are events, command or queries. |
-| [Defining message ownership roles](#defining-message-ownership-roles) | AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event). |
+| [Defining message ownership roles](#defining-message-ownership-roles) | Decide which service owns a shared message contract. By default, `send`/`publish` operations own the contract and `receive`/`subscribe` operations reference it. Use `x-eventcatalog-role` when you need to override that behavior. |
 | [Defining message versions](#defining-message-versions) | In EventCatalog you can version your domains, services and all your messages. This can be useful as you can specify which version of a message your service produces or consumes. |
 | [Mapping channels into EventCatalog](#mapping-channels-into-eventcatalog) | EventCatalog supports [Channels](/docs/development/guides/resources/messages/message-channels/introduction) ([see demo](https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0)). This let's you document how messages or organized and transported in your event-driven architecture. |
 | [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | You can create draft domains, services and messages in EventCatalog from your AsyncAPI files. This will be used to mark the resources as draft in EventCatalog. |
@@ -53,47 +53,60 @@ You can see more [examples of the extension on the demo project](https://github.
 
 <AddedIn version="2.4.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
 
-AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
+EventCatalog stores a message as one shared contract, even when several AsyncAPI files reference it. The generator therefore needs to decide which service can create or update that contract.
 
-By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
+By default, ownership follows the AsyncAPI operation direction:
 
-If you want to define ownership of messages in your files you can use the `x-eventcatalog-role` extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
+| AsyncAPI operation | Relationship to the contract | Generator behavior |
+|--------------------|------------------------------|--------------------|
+| `send` or `publish` | Owner | Creates the message and may update an existing contract. |
+| `receive` or `subscribe` | Reference | Uses the existing contract without overwriting it. If the message does not exist, the receiver creates a fallback from its own definition. |
 
-The available extension values are:
+The service relationship is recorded independently of ownership. Owners are added to the service's `sends`, while references are added to its `receives`.
 
-- `provider`: Generator will generate a new message considering the service is the owner of message contract (`default`).
-- `client`: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
+:::info Default changed in generator v7
+Before v7, every message without an explicit role was treated as owned by the service being generated. This meant a consumer could overwrite the producer's summary or schema.
 
-```js title="x-eventcatalog-role example"
-components:
-  messages:
-    SendOrderConfirmation:
-      description: 'Command received to ask for sending an Order confirmation notification'
-      x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
-```
+To retain the previous ownership behavior for a receiving operation, set `x-eventcatalog-role: provider` explicitly.
+:::
 
-You can see more [examples of the extension on the demo project](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/tree/main/asyncapi-files).
+#### Receiver fallbacks
+
+If a receiving service is generated before the message exists, EventCatalog creates a fallback beneath that service. This keeps consumer-only catalogs working.
 
-AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
+When the producing service is generated later for the same message and version, its definition becomes authoritative and the fallback is moved to the producer's message location. This makes the final contract independent of whether the producer or consumer was generated first.
 
-By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
+#### Override the inferred role
 
-If you want to define ownership of messages in your files you can use the `x-eventcatalog-role` extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
+Use `x-eventcatalog-role` on an operation or message when operation direction does not express the ownership you need:
 
-The available extension values are:
+- `provider`: The service owns the message contract and may create or update it.
+- `client`: The contract is external to the service. The generator records the `sends` or `receives` relationship but does not create or modify the message documentation.
 
-- `provider`: Generator will generate a new message considering the service is the owner of message contract (`default`).
-- `client`: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
+An operation-level role takes precedence over a message-level role. This is useful when a shared message has a different role for each operation or service.
 
-```js title="x-eventcatalog-role example"
+```yaml title="Receiving service that explicitly owns the contract"
+operations:
+  receiveOrderPlaced:
+    action: receive
+    x-eventcatalog-role: provider
+    channel:
+      $ref: '#/channels/orders'
+    messages:
+      - $ref: '#/channels/orders/messages/OrderPlaced'
+```
+
+You can also set the role on the message:
+
+```yaml title="External message"
 components:
   messages:
-    SendOrderConfirmation:
-      description: 'Command received to ask for sending an Order confirmation notification'
-      x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
+    PaymentProcessed:
+      description: Payment processed by an external provider
+      x-eventcatalog-role: client
 ```
 
-You can see more [examples of the extension on the demo project](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/tree/main/asyncapi-files).
+See [Shared message contracts across producer and consumer specs](/docs/plugins/asyncapi/03a-workflows#shared-message-contracts-across-producer-and-consumer-specs) for a complete workflow.
 
 ### Defining message versions
 

package/dist/docs/plugins/asyncapi/03a-workflows.md

@@ -16,6 +16,8 @@ Many companies have different needs, so we have provided a few different workflo
 
 - [Simple mapping between AsyncAPI files and EventCatalog services](#simple-mapping-between-asyncapi-files-and-eventcatalog-services)
   - Map a single AsyncAPI file to a single EventCatalog service
+- [Shared message contracts across producer and consumer specs](#shared-message-contracts-across-producer-and-consumer-specs)
+  - Keep the producer's message contract authoritative when several services reference it
 - [Independent message versions from your AsyncAPI file](#independent-message-versions-from-your-asyncapi-file)
   - Version your messages independently of the service version
 - [Mapping multiple AsyncAPI files to a single EventCatalog service](#mapping-multiple-asyncapi-files-to-a-single-eventcatalog-service)
@@ -48,7 +50,64 @@ generators: [
 ],
 ```
 
-### Independent message versions from your AsyncAPI file
+## Shared message contracts across producer and consumer specs
+
+This workflow is useful when several AsyncAPI files describe the same message. For example, an order service may send `OrderPlaced` while notification and fulfillment services receive it.
+
+EventCatalog stores one shared message contract for a given message ID and version. Without an explicit `x-eventcatalog-role`, the generator uses the AsyncAPI operation direction to determine how each service relates to that contract:
+
+- `send` or `publish` operations own the message contract and may update it.
+- `receive` or `subscribe` operations reference an existing contract without overwriting it.
+- A receiver creates a fallback from its own AsyncAPI definition only when the message does not exist yet.
+- If the producer is generated after a receiver fallback, the producer's definition replaces the fallback and becomes authoritative.
+
+The services can be configured in either order:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'notification-service.yml'), id: 'notification-service' },
+        { path: path.join(__dirname, 'asyncapi-files', 'order-service.yml'), id: 'order-service' },
+      ],
+    },
+  ],
+],
+```
+
+Given these operations, `order-service` owns `OrderPlaced` and `notification-service` references it:
+
+```yaml title="order-service.yml"
+operations:
+  sendOrderPlaced:
+    action: send
+    channel:
+      $ref: '#/channels/orders'
+    messages:
+      - $ref: '#/channels/orders/messages/OrderPlaced'
+```
+
+```yaml title="notification-service.yml"
+operations:
+  receiveOrderPlaced:
+    action: receive
+    channel:
+      $ref: '#/channels/orders'
+    messages:
+      - $ref: '#/channels/orders/messages/OrderPlaced'
+```
+
+Both services remain connected to the message: the producer has an entry in `sends` and the consumer has an entry in `receives`. Only the producer can replace the shared contract.
+
+:::tip Explicit ownership
+If a receiving operation should own the contract, add `x-eventcatalog-role: provider` to that operation or message. Use `x-eventcatalog-role: client` when a sending or receiving service should only record its relationship and must never create the message documentation.
+
+Read [Defining message ownership roles](/docs/plugins/asyncapi/features#defining-message-ownership-roles) for the complete rules.
+:::
+
+## Independent message versions from your AsyncAPI file
 
 This is useful if you want to version your messages separately from the AsyncAPI file.
 
@@ -150,4 +209,4 @@ generators: [
       },
     ],
   ],
-```
+```

package/dist/docs/plugins/openapi/02-plugin-configuration.md

@@ -33,7 +33,7 @@ Each service in the `services` array requires the following properties:
 |----------|------|----------|-------------|
 | `id` | string | Yes | EventCatalog ID for the service. |
 | `path` | string or string[] | Yes | Path/s to your OpenAPI file or remote URL to the OpenAPI file. v6.0.0 introduced the ability to map multiple OpenAPI files to a single service. |
-| `version` | string | No | Version for the generated EventCatalog service and messages. If not provided, the version from the OpenAPI `info.version` field is used. |
+| `version` | string | No | Version for the generated EventCatalog service and messages. If not provided, the OpenAPI `info.version` is used. For a `path` array, the highest `info.version` is selected using semantic version ordering and all specifications are attached to that service version. |
 | `name` | string | No | Display name for the service. If not provided, the specification will be used. _Added in v7.4.3_|
 | `summary` | string | No | Short summary of the service. If not provided, the specification will be used. _Added in v7.4.3_|
 | `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. |
@@ -330,4 +330,3 @@ or refer to the [OpenAPI examples on GitHub](https://github.com/event-catalog/ge
 
 
 
-

package/dist/docs/plugins/openapi/03-features.md

@@ -294,6 +294,8 @@ This can be useful if you want to introduce a new endpoint, but warn users that
 
 If your service exposes multiple APIs, you can map many OpenAPI files to a single service.
 
+One service configuration entry represents one EventCatalog service version. Every file in the `path` array is attached to that service version.
+
 ```js title="eventcatalog.config.js"
 // ..rest of file
 generators: [
@@ -304,10 +306,10 @@ generators: [
         // Here we map two OpenAPI files to a single service
         { 
           path: [
-            path.join(__dirname, 'openapi-files', 'orders-service-v1.yml'),
-            path.join(__dirname, 'openapi-files', 'orders-service-v2.yml')
+            path.join(__dirname, 'openapi-files', 'orders-public-api.yml'),
+            path.join(__dirname, 'openapi-files', 'orders-admin-api.yml')
           ], 
-          id: 'orders-service', owners: ['dboyne', 'team-1'] 
+          id: 'orders-service', version: '3.0.0', owners: ['dboyne', 'team-1']
         },
       ],
       // You can also set owners to the domain, this does not cascade to the services or messages
@@ -323,11 +325,11 @@ generators: [
 
 #### How does mapping multiple OpenAPI files to a single service work?
 
-The OpenAPI plugin will parse all the files in the `path` array. The are ordered by version (info.version).
+The OpenAPI plugin parses every file in the `path` array and adds every specification to the same service version.
 
-Old versions are parsed first and versioned in your catalog along side the messages.
+When `version` is configured on the service entry, it is used for the service and its generated messages. When it is omitted, the highest OpenAPI `info.version` in the array is selected using semantic version ordering.
 
-The latest version is parsed last and will be used as the current version in your catalog.
+The files in a `path` array do not create separate historical service records. To model service history, configure a separate service entry with an explicit `version` for each OpenAPI file. See [OpenAPI workflows](/docs/plugins/openapi/03a-workflows#creating-versioned-service-records) for examples.
 
 You can try this demo out for yourself by running the [mapping-many-openapi-files-to-a-service example](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/mapping-many-openapi-files-to-a-service).
 

package/dist/docs/plugins/openapi/03a-workflows.md

@@ -19,7 +19,11 @@ Many companies have different needs, so we have provided a few different workflo
 - [Independent message versions from your OpenAPI file](#independent-message-versions-from-your-openapi-file)
   - Version your messages independently of the service version
 - [Mapping multiple OpenAPI files to a single EventCatalog service](#mapping-multiple-openapi-files-to-a-single-eventcatalog-service)
-  - Map multiple OpenAPI files to a single EventCatalog service
+  - Attach multiple OpenAPI specifications to one service version
+- [Creating versioned service records](#creating-versioned-service-records)
+  - Use separate service entries when each specification represents a service version
+- [Versioning a service on a later generator run](#versioning-a-service-on-a-later-generator-run)
+  - Preserve the current service as history when a newer version is generated
 - [Mapping OpenAPI and AsyncAPI files to the same EventCatalog service](#mapping-openapi-and-asyncapi-files-to-the-same-eventcatalog-service)
   - Map an OpenAPI and AsyncAPI file to the same EventCatalog service
 
@@ -29,7 +33,9 @@ _If we are missing a workflow that you think is useful, please raise an [issue o
 
 This is the simplest workflow and is useful if you have a single OpenAPI file per service.
 
-EventCatalog will parse your OpenAPI file and map it's specification to the service you define. 
+EventCatalog will parse your OpenAPI file and map its specification to the service you define.
+
+If you do not configure a service `version`, the OpenAPI document's `info.version` is used.
 
 This will document your service, and the messages it produces and consumes.
 
@@ -79,44 +85,99 @@ paths:
 
 In the example above, the message `listOrders` will be versioned as `2.0.0` and all other messages will be versioned as `1.0.0`.
 
-You can read more about message versioning in the [Features](/docs/plugins/openapi/features#defining-message-versions) section.
+You can read more about message versioning in the [Features](/docs/plugins/openapi/features#custom-versioning-with-x-eventcatalog-message-version) section.
 
 ## Mapping multiple OpenAPI files to a single EventCatalog service
 
-This is useful if you have a single service that produces and consumes multiple OpenAPI versions.
+This is useful when one version of a service exposes multiple OpenAPI contracts, for example a public API and an administration API.
+
+Use a `path` array in one service entry. One service entry represents one EventCatalog service version, so every OpenAPI file in the array is attached to that version and rendered in the service's `specifications` list.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        {
+          id: 'orders-service',
+          version: '3.0.0',
+          path: [
+            path.join(__dirname, 'openapi-files', 'orders-public-api.yml'),
+            path.join(__dirname, 'openapi-files', 'orders-admin-api.yml'),
+          ],
+        },
+      ],
+    },
+  ],
+],
+```
+
+The generated service contains both specifications:
+
+```yaml
+id: orders-service
+version: 3.0.0
+specifications:
+  - type: openapi
+    path: orders-public-api.yml
+    name: Orders Public API
+  - type: openapi
+    path: orders-admin-api.yml
+    name: Orders Admin API
+```
+
+:::info Choosing the service version
+When `version` is configured on the service entry, it takes precedence over the `info.version` values in the OpenAPI files.
 
-Some people call this a "polyglot" service, as it produces and consumes multiple APIs.
+When `version` is omitted, the generator uses the highest OpenAPI `info.version` from the `path` array. Versions are compared semantically, so `10.0.0` is considered newer than `2.0.0`. Every specification in the array is then attached to that selected service version.
+
+A `path` array does not create historical service records. Use separate service entries if the files represent different versions of the service.
+:::
+
+## Creating versioned service records
+
+Use a separate service entry for each service version when you want to keep multiple versions in EventCatalog. Set `version` explicitly to make the intended service lifecycle clear.
 
 ```js title="eventcatalog.config.js"
 // ...rest of file
 generators: [
   [
-    '@eventcatalog/generator-asyncapi',
+    '@eventcatalog/generator-openapi',
     {
       services: [
-        // Version 1 of the OpenAPI file
-        { path: path.join(__dirname, 'openapi-files', 'orders-service-v1.yml'), id: 'orders-service' },
-        // Version 2 of the AsyncAPI File
-        { path: path.join(__dirname, 'openapi-files', 'orders-service-v2.yml'), id: 'orders-service' },
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          path: path.join(__dirname, 'openapi-files', 'orders-service-v1.yml'),
+        },
+        {
+          id: 'orders-service',
+          version: '2.0.0',
+          path: path.join(__dirname, 'openapi-files', 'orders-service-v2.yml'),
+        },
       ],
     },
   ],
 ],
 ```
 
-:::info Versioning
-When you map multiple versions of an OpenAPI file to a single service, the `version` property in your OpenAPI files needs to be the same.
+In this example, `2.0.0` becomes the current service. Version `1.0.0` and its OpenAPI specification are stored as a historical service record under `versioned/1.0.0`. Each service version references only the OpenAPI specification configured for that entry.
 
-If they are different, EventCatalog will version the previous versions of your service.
+You can also use a `path` array inside either entry if that particular service version has multiple OpenAPI specifications.
 
-In the example above, the `version` property in the OpenAPI files is `1.0.0` and `2.0.0`.
+## Versioning a service on a later generator run
 
-EventCatalog will version the service as `1.0.0` and `2.0.0`.
+You do not need to keep every historical version in `eventcatalog.config.js` forever. If `orders-service` is generated as `1.0.0` today and the configured OpenAPI file changes to `2.0.0` later, running the generator again will:
 
-The messages in the service will be versioned as `1.0.0` and `2.0.0`.
+1. Move the existing `1.0.0` service and its OpenAPI specification into the service's versioned history.
+2. Generate `2.0.0` as the current service with the new OpenAPI specification.
 
-This allows you to track the history of your service and the messages in it.
+This works when the service version comes from OpenAPI `info.version` or from an explicit `version` in the service configuration. If you configure `version`, update it when you intend to create a new service version.
 
+:::tip Multiple contracts versus service history
+Use one entry with `path: []` for multiple contracts belonging to the same service version. Use separate entries, or update the version on a later run, to create service history.
 :::
 
 ## Mapping OpenAPI and AsyncAPI files to the same EventCatalog service
@@ -150,4 +211,4 @@ generators: [
       },
     ],
   ],
-```
+```

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -1,6 +1,6 @@
 import {
   log_build_default
-} from "./chunk-25RQCO2H.js";
+} from "./chunk-QFXV3GDK.js";
 import "./chunk-K2XIENVT.js";
 import {
   runMigrations
@@ -14,10 +14,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-YBNWZEFQ.js";
+} from "./chunk-XTC5VFLE.js";
 import {
   logger
-} from "./chunk-T6UEDS2J.js";
+} from "./chunk-CQQE7NTL.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -27,7 +27,7 @@ import {
 import {
   watch
 } from "./chunk-CAJUIMDJ.js";
-import "./chunk-BYH34SOZ.js";
+import "./chunk-5L4FYIAY.js";
 import {
   createAstroDevLineFilter,
   createAstroLineFilter
@@ -38,7 +38,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-W4UBACYZ.js";
+} from "./chunk-OPFRJOPV.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-YBNWZEFQ.js";
-import "./chunk-T6UEDS2J.js";
-import "./chunk-W4UBACYZ.js";
+} from "./chunk-XTC5VFLE.js";
+import "./chunk-CQQE7NTL.js";
+import "./chunk-OPFRJOPV.js";
 import "./chunk-6QENHZZP.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-T6UEDS2J.js";
-import "../chunk-W4UBACYZ.js";
+} from "../chunk-CQQE7NTL.js";
+import "../chunk-OPFRJOPV.js";
 export {
   logger
 };

package/eventcatalog/src/components/LatestVersionRedirect.astro

@@ -0,0 +1,26 @@
+---
+import Seo from '@components/Seo.astro';
+
+interface Props {
+  redirectUrl: string;
+  title: string;
+}
+
+const { redirectUrl, title } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <Seo title={title} />
+    <meta http-equiv="refresh" content={`0;url=${redirectUrl}`} />
+  </head>
+  <body>
+    <p>You are being redirected to <a href={redirectUrl}>{redirectUrl}</a></p>
+  </body>
+</html>
+
+<script define:vars={{ redirectUrl }}>
+  const fullRedirectUrl = redirectUrl + window.location.search + window.location.hash;
+  window.location.replace(fullRedirectUrl);
+</script>

package/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx

@@ -13,7 +13,7 @@ import {
   removeFavorite as removeFavoriteAction,
   type FavoriteItem,
 } from '@stores/favorites-store';
-import { getBadgeClasses, isGroupCollapsed } from './utils';
+import { canCollapseGroup, getBadgeClasses, getGroupLabel, isGroupCollapsed } from './utils';
 import { resolveIconUrl } from '@utils/icon';
 
 const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
@@ -57,7 +57,7 @@ export default function NestedSideBar() {
   const [slideDirection, setSlideDirection] = useState<'forward' | 'backward' | null>(null);
   const [isInitialized, setIsInitialized] = useState(false);
   const [currentPath, setCurrentPath] = useState<string>('');
-  const [collapsedSections, setCollapsedSections] = useState<Set<string>>(new Set());
+  const [sectionCollapsePreferences, setSectionCollapsePreferences] = useState(loadCollapsedSections);
   const [showPathPreview, setShowPathPreview] = useState(false);
   const [showFullPath, setShowFullPath] = useState(false);
 
@@ -95,29 +95,23 @@ export default function NestedSideBar() {
    * Toggle section collapse state
    */
   const toggleSectionCollapse = (sectionId: string) => {
-    setCollapsedSections((prev) => {
-      const next = new Set(prev);
-      if (next.has(sectionId)) {
-        next.delete(sectionId);
+    setSectionCollapsePreferences((previousPreferences) => {
+      const nextPreferences = {
+        expanded: new Set(previousPreferences.expanded),
+      };
+      const isCurrentlyCollapsed = isGroupCollapsed(true, sectionId, previousPreferences);
+
+      if (isCurrentlyCollapsed) {
+        nextPreferences.expanded.add(sectionId);
       } else {
-        next.add(sectionId);
+        nextPreferences.expanded.delete(sectionId);
       }
-      // Save to localStorage
-      saveCollapsedSections(next);
-      return next;
+
+      saveCollapsedSections(nextPreferences);
+      return nextPreferences;
     });
   };
 
-  /**
-   * Load collapsed sections from localStorage on mount
-   */
-  useEffect(() => {
-    const saved = loadCollapsedSections();
-    if (saved.size > 0) {
-      setCollapsedSections(saved);
-    }
-  }, []);
-
   /**
    * Update navigation stack when roots become available
    */
@@ -521,7 +515,7 @@ export default function NestedSideBar() {
   // Show loading state if no data yet
   if (!data || roots.length === 0) {
     return (
-      <aside className="w-full min-h-full flex-1 flex flex-col font-sans bg-[rgb(var(--ec-rail-bg))]">
+      <aside className="flex h-full min-h-0 w-full flex-1 flex-col bg-[rgb(var(--ec-rail-bg))] font-sans">
         {/* Search skeleton */}
         <div className="px-4 py-3 border-b border-[rgb(var(--ec-content-border))] bg-[rgb(var(--ec-rail-bg))]">
           <div className="h-10 bg-[rgb(var(--ec-content-hover))] rounded-xl animate-pulse" />
@@ -754,9 +748,9 @@ export default function NestedSideBar() {
         return child && isVisible(child);
       }) ?? [];
 
-    const groupId = groupKey || group.collapseKey || `group-${index}`;
-    const canCollapse = visibleChildren.length > 3;
-    const isCollapsed = isGroupCollapsed(canCollapse, groupId, collapsedSections);
+    const groupId = groupKey || group.collapseKey || `${currentLevel.key ?? 'root'}:group:${group.title}`;
+    const canCollapse = canCollapseGroup(visibleChildren.length);
+    const isCollapsed = isGroupCollapsed(canCollapse, groupId, sectionCollapsePreferences);
 
     // When a group's children are subtle subgroups (e.g. Resources > Services/Flows/Data Stores),
     // they render flush under the parent icon instead of inside the indented border guide.
@@ -787,7 +781,7 @@ export default function NestedSideBar() {
                 : 'text-[12px] font-semibold tracking-tight text-[rgb(var(--ec-content-text))]'
             )}
           >
-            {group.title}
+            {getGroupLabel(group.title, visibleChildren.length)}
           </span>
         </div>
         {canCollapse && (
@@ -973,7 +967,7 @@ export default function NestedSideBar() {
   };
 
   return (
-    <aside className="w-full min-h-full flex-1 flex flex-col font-sans bg-[rgb(var(--ec-rail-bg))]">
+    <aside className="flex h-full min-h-0 w-full flex-1 flex-col bg-[rgb(var(--ec-rail-bg))] font-sans">
       {isTopLevel && (
         <div className="flex h-[60px] items-center px-6 bg-[rgb(var(--ec-rail-bg)/0.98)] backdrop-blur-sm border-b border-[rgb(var(--ec-content-border))] sticky top-0 z-10">
           <span className="text-[0.65rem] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-sidebar-text)/0.5)] truncate">
@@ -1128,7 +1122,7 @@ export default function NestedSideBar() {
       {/* Navigation Content */}
       <nav
         key={animationKey}
-        className={cn('flex-1 overflow-y-auto overflow-x-hidden p-4 px-2', getAnimationClass())}
+        className={cn('min-h-0 flex-1 overflow-y-auto overflow-x-hidden p-4 px-2', getAnimationClass())}
         style={{
           scrollbarWidth: 'thin',
           scrollbarColor: 'rgb(var(--ec-content-border)) transparent',