feat(songs): add portable htksong packages

Author: Codewriter90x

docs/development/chart-creator.md

@@ -28,12 +28,31 @@ The exporter creates a new, never-overwritten folder under
 - `song.json`;
 - `notes.json`.
 
+It also creates one portable `<song-id>.htksong` file alongside the folder.
+The package is a ZIP-compatible, chart-only container with exactly three
+entries:
+
+- `htksong-version` (`1`);
+- `song.json`;
+- `notes.json`.
+
+To transfer a take, copy only the `.htksong` file into
+`Documents/HTKSongs` on the other computer and refresh the Song Library. The
+game validates and atomically imports it. Existing song folders are never
+overwritten.
+
 The publish is atomic and both documents are parsed by the production loaders
-before the folder becomes visible. The manifest declares chart availability but
+before the folder or package becomes visible. The manifest declares chart availability but
 keeps audio as `missing`. Chart Creator never copies, embeds, downloads, or
 redistributes the source audio. To play or share the take, the user must add an
 audio file they are entitled to use and update the local binding explicitly.
 
+Import is fail-closed. Unknown/archive entries, audio declarations, symbolic
+links, duplicate names, unsupported versions, malformed JSON, invalid charts,
+oversized data and path traversal are rejected before extraction. Version 1 is
+intentionally chart-only; adding optional distributable audio requires a future
+explicit package version and rights-aware UX.
+
 The exported title is marked `Recorded Take` and the difficulty hint says that
 the performance must be reviewed before sharing. This is a captured performance,
 not a claim of authoritative transcription.

docs/development/song-library.md

@@ -94,3 +94,19 @@ machine-specific path into bundled `song.json`.
 The refresh button performs an explicit rescan. Discovery does not watch the
 filesystem continuously, allocate every frame, or access folders outside the
 two configured roots.
+
+## Portable `.htksong` chart packages
+
+Chart Creator writes a portable chart-only package next to each recorded take.
+Copy a `.htksong` file directly into `~/Documents/HTKSongs` and select
+**Refresh library**. Before normal folder discovery, the game validates the
+container and atomically installs its `song.json` and `notes.json` into a folder
+named after the validated song ID. The package remains in place so it can be
+copied to another computer; subsequent refreshes are idempotent.
+
+Package schema version 1 contains no audio and rejects any audio declaration or
+extra archive entry. Imports are bounded to 5 MiB, reject links, duplicate or
+case-colliding names, malformed ZIP/JSON/chart data, unsupported versions and
+path traversal, and never replace an existing song folder. An imported chart is
+therefore visible but unavailable until the player explicitly supplies audio
+they are entitled to use through the ordinary local song binding.

src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/ChartCreator.cs

@@ -263,17 +263,24 @@ public ProjectedHit(double timeSeconds, DrumPad pad, int recordingIndex)
 
     public sealed class ChartCreatorExportResult
     {
-        internal ChartCreatorExportResult(string songId, string folderPath, string chartPath, string manifestPath)
+        internal ChartCreatorExportResult(
+            string songId,
+            string folderPath,
+            string chartPath,
+            string manifestPath,
+            string packagePath)
         {
             SongId = songId;
             FolderPath = folderPath;
             ChartPath = chartPath;
             ManifestPath = manifestPath;
+            PackagePath = packagePath;
         }
         public string SongId { get; }
         public string FolderPath { get; }
         public string ChartPath { get; }
         public string ManifestPath { get; }
+        public string PackagePath { get; }
     }
 
     public sealed class ChartCreatorExporter
@@ -300,8 +307,10 @@ public ChartCreatorExportResult ExportChartOnly(
             string baseId = $"{prefix}-take-{createdAtUtc:yyyyMMdd-HHmmss}";
             string songId = UniqueSongId(root, baseId);
             string destination = Path.Combine(root, songId);
+            string packagePath = Path.Combine(root, songId + HtkSongPackageService.Extension);
             string temporary = Path.Combine(root, $".hitthekit-chart-{Guid.NewGuid():N}");
             Directory.CreateDirectory(temporary);
+            bool destinationPublished = false;
             try
             {
                 string chartJson = ChartCreatorJson.Serialize(draft, metadata.Difficulty, metadata.Bpm, quantization);
@@ -314,15 +323,19 @@ public ChartCreatorExportResult ExportChartOnly(
                 new ChartLoader().Load(chartJson, metadata.Difficulty);
                 new SongLibraryDiscovery().Parse(File.ReadAllText(manifestPath), temporary, SongLibraryOrigin.UserFolder);
                 Directory.Move(temporary, destination);
+                destinationPublished = true;
+                new HtkSongPackageService().CreateChartOnlyPackage(destination, packagePath);
                 return new ChartCreatorExportResult(
                     songId,
                     destination,
                     Path.Combine(destination, "notes.json"),
-                    Path.Combine(destination, "song.json"));
+                    Path.Combine(destination, "song.json"),
+                    packagePath);
             }
             catch
             {
                 if (Directory.Exists(temporary)) Directory.Delete(temporary, true);
+                if (destinationPublished && Directory.Exists(destination)) Directory.Delete(destination, true);
                 throw;
             }
         }
@@ -331,7 +344,9 @@ private static string UniqueSongId(string root, string baseId)
         {
             string value = baseId;
             int suffix = 2;
-            while (Directory.Exists(Path.Combine(root, value))) value = $"{baseId}-{suffix++}";
+            while (Directory.Exists(Path.Combine(root, value)) ||
+                   File.Exists(Path.Combine(root, value + HtkSongPackageService.Extension)))
+                value = $"{baseId}-{suffix++}";
             ChartCreatorMetadata.ValidateIdentifier(value, nameof(baseId));
             return value;
         }

src/HitTheKit.Unity/Assets/HitTheKit/Runtime/Gameplay/GameplayHighwayController.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.IO;
 using HitTheKit.Core;
 using HitTheKit.Unity.Audio;
 using HitTheKit.Unity.Charts;
@@ -124,6 +125,7 @@ public sealed class GameplayHighwayController : MonoBehaviour
         public double CurrentAttemptPracticeSeconds => practiceTimer.CurrentAttemptSeconds;
         public int RecordedChartHitCount => chartRecording?.HitCount ?? chartDraft?.Hits.Count ?? 0;
         public string LastChartExportPath { get; private set; }
+        public string LastChartPackagePath { get; private set; }
 
         private void Awake()
         {
@@ -508,6 +510,7 @@ public void RestartRun()
             resultRecorded = false;
             chartDraft = null;
             LastChartExportPath = null;
+            LastChartPackagePath = null;
             chartRecording?.Restart();
             scoreTracker.Reset();
             keyboardCalibration.Reset();
@@ -643,8 +646,10 @@ public ChartCreatorExportResult SaveChartRecording(ChartQuantization quantizatio
                 SongLibraryRuntime.UserRoot,
                 DateTimeOffset.UtcNow);
             LastChartExportPath = result.FolderPath;
+            LastChartPackagePath = result.PackagePath;
             if (chartCreatorStatusLabel != null)
-                chartCreatorStatusLabel.text = $"SALVATO · {result.SongId} · AGGIUNGI SOLO AUDIO AUTORIZZATO";
+                chartCreatorStatusLabel.text =
+                    $"SALVATO · {Path.GetFileName(result.PackagePath)} · COPIA IL PACCHETTO SU UN ALTRO MAC";
             return result;
         }