From e07c46c49892966a67ab7bcd5e72d214354e4859 Mon Sep 17 00:00:00 2001
From: Filipe Herculano <fifo_@live.com>
Date: Wed, 19 Aug 2026 10:59:26 -0400
Subject: [PATCH] =?UTF-8?q?v0.20.1=20=E2=80=94=20lane=20types=20on=20track?=
 =?UTF-8?q?=20structure?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Types + docs only: Section.lane and StructureResult.lanes for the lane
fields that include_metadata=true responses now carry. Runtime behavior
is unchanged — the fields already flow through on v0.20.0.
---
 CHANGELOG.md  | 6 ++++++
 README.md     | 4 ++--
 src/init.luau | 8 +++++++-
 wally.toml    | 2 +-
 4 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c946add..0327be4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.20.1
+
+### Added
+
+- **Lane types on track structure** — when `include_metadata = true`, each section/phrase now also carries `lane` (its named parallel timeline row) and the result a top-level ordered `lanes` array. This release only adds the Luau type annotations and docs — the fields already flow through at runtime on v0.20.0.
+
 ## v0.20.0
 
 ### Added
diff --git a/README.md b/README.md
index abfc466..4e667d9 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ Add to your `wally.toml`:
 
 ```toml
 [server-dependencies]
-AudioScape = "this-fifo/audioscape-sdk@0.20.0"
+AudioScape = "this-fifo/audioscape-sdk@0.20.1"
 ```
 
 Then run:
@@ -342,7 +342,7 @@ local structure = AudioScape:getStructure(soundInstance)
 
 `label` values come from: `Intro`, `Verse`, `Chorus`, `Drop`, `Bridge`, `Climax`, `Outro`, `Main`, `Break`, `Build`, `Breakdown`, `Transition`, `Peak`. `energy` is `1`–`4`.
 
-**Section metadata:** pass `include_metadata = true` and every section/phrase carries its authored key/value pairs verbatim in `metadata` — custom cue parameters (lighting amounts, movement paths, easing styles) beyond the flattened fields. Entries without authored pairs return an empty table. Drive custom events straight from authored cue sections:
+**Section metadata & lanes:** pass `include_metadata = true` and every section/phrase carries its authored key/value pairs verbatim in `metadata` — custom cue parameters (lighting amounts, movement paths, easing styles) beyond the flattened fields (empty table when none) — plus a `lane` name grouping entries into parallel timeline rows, with the ordered distinct names in a top-level `lanes` array. Entries sharing a lane string belong to the same row; time-overlapping entries in different lanes run concurrently. Drive custom events straight from authored cue sections:
 
 ```lua
 local structure = AudioScape:getStructure({ asset_id = "1843209165", include_metadata = true })
diff --git a/src/init.luau b/src/init.luau
index bc68772..56254d9 100644
--- a/src/init.luau
+++ b/src/init.luau
@@ -423,8 +423,11 @@ export type Section = {
 	color: string?,
 	-- Present only when the structure was fetched with include_metadata =
 	-- true: the entry's authored key/value pairs, verbatim (empty table for
-	-- entries with none).
+	-- entries with none), and its resolved lane — the named parallel timeline
+	-- row this entry belongs to. Entries sharing a lane string are in the
+	-- same row; time-overlapping entries in different lanes run concurrently.
 	metadata: { [string]: string | number }?,
+	lane: string?,
 }
 
 export type StructureResult = {
@@ -439,6 +442,9 @@ export type StructureResult = {
 	-- crossfades to `phrases`; finer cues to `sections`.
 	sections: { Section },
 	phrases: { Section },
+	-- Only with include_metadata = true: ordered distinct lane names across
+	-- sections + phrases (the grouping key for Section.lane).
+	lanes: { string }?,
 }
 
 export type BeatHit = {
diff --git a/wally.toml b/wally.toml
index 15d32a6..46c9912 100644
--- a/wally.toml
+++ b/wally.toml
@@ -1,6 +1,6 @@
 [package]
 name = "this-fifo/audioscape-sdk"
-version = "0.20.0"
+version = "0.20.1"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "server"
 license = "MIT"