update sdk and skills

Author: KSemenenko

README.md

@@ -936,8 +936,10 @@ Renderers should use **text size, letter spacing, weight, and animation** to com
 | `[legato]` | Normal | Tighter (-0.5px) | Normal | Smooth underline or wave |
 | `[staccato]` | Normal | Wider (+1–2px) | Bold | Dotted underline or dashes between words |
 | `[energy:1–4]` | Smaller (90%) | Normal | Light | Lower opacity |
+| `[energy:5–6]` | Normal | Normal | Normal | Default styling (no special treatment) |
 | `[energy:7–10]` | Larger (110–130%) | Normal | Bold | Glow or pulsing effect |
 | `[melody:1–3]` | Normal | Normal | Normal | Flat visual indicator (dash) |
+| `[melody:4–6]` | Normal | Normal | Normal | Default styling (no special treatment) |
 | `[melody:7–10]` | Normal | Normal | Normal | Wave or oscillating indicator |
 
 These are **recommendations**, not requirements. Renderers may adapt the visual treatment to their platform. The key principle: the reader should **feel** the delivery instruction from the visual presentation alone.

SDK/dotnet/src/ManagedCode.Tps/AGENTS.md

@@ -66,3 +66,10 @@ For this .NET project:
 - Keep the `ManagedCode.Tps` namespace prefix intact.
 - Do not place test helpers or test-only code in this project.
 - Prefer small, composable types over large utility buckets.
+
+## Exception Record
+
+- Size exception:
+  - scope: `TpsPlaybackSession.cs`, `Internal/TpsContentCompiler.cs`, `Internal/TpsParser.cs`, `Models/Contracts.cs`
+  - reason: these files still concentrate the parity-first .NET implementation of the runtime contract
+  - removal plan: split playback transition/publish code, parser header/front-matter code, content-scope handling, and transport contracts into smaller cohesive types

SDK/dotnet/src/ManagedCode.Tps/Models/PlaybackContracts.cs

@@ -11,6 +11,27 @@ public enum TpsPlaybackStatus
     Completed
 }
 
+public static class TpsPlaybackDefaults
+{
+    public const int DefaultSpeedStepWpm = 10;
+    public const int DefaultTickIntervalMs = 16;
+    public const int MinimumSpeedStepWpm = 1;
+    public const int MinimumTickIntervalMs = 1;
+}
+
+public static class TpsPlaybackEventNames
+{
+    public const string StateChanged = "stateChanged";
+    public const string WordChanged = "wordChanged";
+    public const string PhraseChanged = "phraseChanged";
+    public const string BlockChanged = "blockChanged";
+    public const string SegmentChanged = "segmentChanged";
+    public const string StatusChanged = "statusChanged";
+    public const string Completed = "completed";
+    public const string SnapshotChanged = "snapshotChanged";
+    public const string ObserveSnapshot = "observeSnapshot";
+}
+
 public class TpsPlaybackSessionOptions
 {
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
@@ -29,14 +50,14 @@ public int SpeedStepWpm
     {
         get;
         init => field = value > 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "SpeedStepWpm must be greater than zero.");
-    } = 10;
+    } = TpsPlaybackDefaults.DefaultSpeedStepWpm;
 
     [JsonPropertyName("tickIntervalMs")]
     public int TickIntervalMs
     {
         get;
         init => field = value > 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "TickIntervalMs must be greater than zero.");
-    } = 16;
+    } = TpsPlaybackDefaults.DefaultTickIntervalMs;
 
     [JsonIgnore]
     public TimeProvider TimeProvider

SDK/dotnet/src/ManagedCode.Tps/TpsPlaybackSession.cs

@@ -104,7 +104,7 @@ public IDisposable ObserveSnapshot(Action<TpsPlaybackSnapshot> observer, bool em
 
         if (emitCurrent)
         {
-            InvokeSnapshotObserver("observeSnapshot", observer, CreateSnapshot(), subscription);
+            InvokeSnapshotObserver(TpsPlaybackEventNames.ObserveSnapshot, observer, CreateSnapshot(), subscription);
         }
 
         return subscription;
@@ -685,45 +685,45 @@ private void Publish(Transition transition)
     {
         if (transition.StatusChangedRaised)
         {
-            InvokeHandlers("statusChanged", StatusChanged, new TpsPlaybackStatusChangedEventArgs(transition.State, transition.PreviousStatus, transition.Status), transition.Snapshot);
+            InvokeHandlers(TpsPlaybackEventNames.StatusChanged, StatusChanged, new TpsPlaybackStatusChangedEventArgs(transition.State, transition.PreviousStatus, transition.Status), transition.Snapshot);
         }
 
         if (transition.StateChangedRaised)
         {
             var args = new TpsPlaybackStateChangedEventArgs(transition.State, transition.PreviousState, transition.Status);
-            InvokeHandlers("stateChanged", StateChanged, args, transition.Snapshot);
+            InvokeHandlers(TpsPlaybackEventNames.StateChanged, StateChanged, args, transition.Snapshot);
 
             if (transition.WordChangedRaised)
             {
-                InvokeHandlers("wordChanged", WordChanged, args, transition.Snapshot);
+                InvokeHandlers(TpsPlaybackEventNames.WordChanged, WordChanged, args, transition.Snapshot);
             }
 
             if (transition.PhraseChangedRaised)
             {
-                InvokeHandlers("phraseChanged", PhraseChanged, args, transition.Snapshot);
+                InvokeHandlers(TpsPlaybackEventNames.PhraseChanged, PhraseChanged, args, transition.Snapshot);
             }
 
             if (transition.BlockChangedRaised)
             {
-                InvokeHandlers("blockChanged", BlockChanged, args, transition.Snapshot);
+                InvokeHandlers(TpsPlaybackEventNames.BlockChanged, BlockChanged, args, transition.Snapshot);
             }
 
             if (transition.SegmentChangedRaised)
             {
-                InvokeHandlers("segmentChanged", SegmentChanged, args, transition.Snapshot);
+                InvokeHandlers(TpsPlaybackEventNames.SegmentChanged, SegmentChanged, args, transition.Snapshot);
             }
 
             if (transition.CompletedRaised)
             {
-                InvokeHandlers("completed", Completed, args, transition.Snapshot);
+                InvokeHandlers(TpsPlaybackEventNames.Completed, Completed, args, transition.Snapshot);
             }
         }
         else if (transition.CompletedRaised)
         {
-            InvokeHandlers("completed", Completed, new TpsPlaybackStateChangedEventArgs(transition.State, transition.PreviousState, transition.Status), transition.Snapshot);
+            InvokeHandlers(TpsPlaybackEventNames.Completed, Completed, new TpsPlaybackStateChangedEventArgs(transition.State, transition.PreviousState, transition.Status), transition.Snapshot);
         }
 
-        InvokeHandlers("snapshotChanged", SnapshotChanged, new TpsPlaybackSnapshotChangedEventArgs(transition.Snapshot), transition.Snapshot);
+        InvokeHandlers(TpsPlaybackEventNames.SnapshotChanged, SnapshotChanged, new TpsPlaybackSnapshotChangedEventArgs(transition.Snapshot), transition.Snapshot);
     }
 
     private void InvokeHandlers<TEventArgs>(string eventName, EventHandler<TEventArgs>? handlers, TEventArgs args, TpsPlaybackSnapshot snapshot)

SDK/dotnet/tests/ManagedCode.Tps.Tests/TpsPlaybackSessionTests.cs

@@ -374,6 +374,26 @@ public void PlaybackSession_ObserveSnapshot_DoesNotReplayAfterImmediateDispose()
         Assert.Empty(snapshots);
     }
 
+    [Fact]
+    public void PlaybackSession_ObserveSnapshot_CanSkipInitialReplay_AndExplicitOffStopsFurtherEvents()
+    {
+        var script = TpsRuntime.Compile("## [Signal]\n### [Body]\nReady now.").Script;
+        using var session = new TpsPlaybackSession(script);
+        var snapshots = new List<TpsPlaybackSnapshot>();
+        var statuses = new List<TpsPlaybackStatus>();
+
+        using var subscription = session.ObserveSnapshot(snapshot => snapshots.Add(snapshot), emitCurrent: false);
+        EventHandler<TpsPlaybackSnapshotChangedEventArgs> handler = (_, args) => statuses.Add(args.Snapshot.Status);
+        session.SnapshotChanged += handler;
+
+        session.NextWord();
+        session.SnapshotChanged -= handler;
+        session.PreviousWord();
+
+        Assert.Equal("now.", snapshots[0].State.CurrentWord?.CleanText);
+        Assert.Equal([TpsPlaybackStatus.Paused], statuses);
+    }
+
     [Fact]
     public void StandalonePlayer_CompilesSourceAndExposesRuntimeSnapshotAndControls()
     {

SDK/dotnet/tests/ManagedCode.Tps.Tests/TpsRuntimeTests.cs

@@ -12,6 +12,9 @@ public void PublicSurface_ExposesConstantsAndContracts()
         Assert.Equal(140, TpsSpec.DefaultBaseWpm);
         Assert.Equal("neutral", TpsSpec.DefaultEmotion);
         Assert.Equal("WPM", TpsSpec.WpmSuffix);
+        Assert.Equal(10, TpsPlaybackDefaults.DefaultSpeedStepWpm);
+        Assert.Equal(16, TpsPlaybackDefaults.DefaultTickIntervalMs);
+        Assert.Equal("snapshotChanged", TpsPlaybackEventNames.SnapshotChanged);
         Assert.Contains(TpsSpec.Tags.Building, TpsSpec.DeliveryModes);
         Assert.Contains(TpsSpec.Tags.Loud, TpsSpec.VolumeLevels);
         Assert.Contains(TpsSpec.Tags.Normal, TpsSpec.RelativeSpeedTags);

SDK/flutter/AGENTS.md

@@ -1,6 +1,58 @@
-# ManagedCode.Tps Flutter SDK
+# AGENTS.md
+
+Project: SDK Flutter runtime
+Owned by: ManagedCode.Tps SDK maintainers
+
+Parent: `../../AGENTS.md`
+
+## Purpose
+
+- Own the Dart runtime consumed by Flutter hosts.
+- Keep compile, validate, restore, player, playback-session, and standalone-player behavior aligned with the other TPS runtimes.
+
+## Entry Points
+
+- `lib/src/managedcode_tps.dart`
+- `lib/managedcode_tps.dart`
+- `test/runtime_test.dart`
+
+## Boundaries
+
+- In scope:
+  - Dart runtime implementation
+  - Flutter-facing package export surface
+  - parity and integration tests for the Dart runtime
+- Out of scope:
+  - widget-layer rendering
+  - TypeScript, .NET, Swift, or Java source changes unless parity requires them
+
+## Project Commands
+
+- `build`: `dart analyze`
+- `test`: `dart test`
+- `coverage`: `./coverage.sh`
+
+## Applicable Skills
+
+- `mcaf-solid-maintainability`
+- `mcaf-testing`
+- `dotnet-mcaf-documentation`
+
+## Local Risks Or Protected Areas
+
+- Shared fixture parity with `SDK/fixtures/**` and `examples/*.tps` is a protected contract.
+- Public runtime models must stay embeddable and UI-framework-neutral.
+- Playback snapshots and event names are transport-facing and must remain stable across runtimes.
+
+## Local Rules
 
-- Runtime contract must stay aligned with `SDK/ts`, `SDK/js`, and `SDK/dotnet`.
-- Validate against `SDK/fixtures/**` and `examples/*.tps`.
-- Keep the package Flutter-compatible and UI-framework-neutral.
 - Prefer immutable public models and deterministic playback math.
+- Keep runtime constants under named SDK types instead of scattering literals through the player/session code.
+- Add regression tests for every playback or compiled-JSON bug fix.
+
+## Exception Record
+
+- Size exception:
+  - scope: `lib/src/managedcode_tps.dart`
+  - reason: the Flutter runtime is still implemented as one parity-first source file while the contract is stabilized across six runtimes
+  - removal plan: split into `constants`, `parser`, `compiler`, `player`, `playback-session`, and `transport` files in the next maintainability pass

SDK/flutter/lib/src/managedcode_tps.dart

@@ -4,6 +4,22 @@ import "dart:math" as math;
 
 enum TpsPlaybackStatus { idle, playing, paused, completed }
 
+abstract final class TpsPlaybackDefaults {
+  static const defaultSpeedStepWpm = 10;
+  static const defaultTickIntervalMs = 16;
+}
+
+abstract final class TpsPlaybackEventNames {
+  static const stateChanged = "stateChanged";
+  static const wordChanged = "wordChanged";
+  static const phraseChanged = "phraseChanged";
+  static const blockChanged = "blockChanged";
+  static const segmentChanged = "segmentChanged";
+  static const statusChanged = "statusChanged";
+  static const completed = "completed";
+  static const snapshotChanged = "snapshotChanged";
+}
+
 class TpsPosition {
   const TpsPosition({
     required this.line,
@@ -1070,7 +1086,7 @@ class TpsPlayer {
 class TpsPlaybackSession {
   TpsPlaybackSession(CompiledScript scriptOrPlayer, [TpsPlaybackSessionOptions options = const TpsPlaybackSessionOptions()])
       : player = TpsPlayer(scriptOrPlayer),
-        tickIntervalMs = options.tickIntervalMs ?? 16,
+        tickIntervalMs = options.tickIntervalMs ?? TpsPlaybackDefaults.defaultTickIntervalMs,
         baseWpm = _normalizeBaseWpm(options.baseWpm),
         speedStepWpm = _normalizeSpeedStep(options.speedStepWpm),
         speedOffsetWpm = 0 {
@@ -1123,7 +1139,7 @@ class TpsPlaybackSession {
   }
 
   VoidCallback observeSnapshot(void Function(TpsPlaybackSnapshot) listener, [bool emitCurrent = true]) {
-    final unsubscribe = on("snapshotChanged", (event) => listener(event as TpsPlaybackSnapshot));
+    final unsubscribe = on(TpsPlaybackEventNames.snapshotChanged, (event) => listener(event as TpsPlaybackSnapshot));
     if (emitCurrent) {
       listener(snapshot);
     }
@@ -1306,7 +1322,7 @@ class TpsPlaybackSession {
     }
   }
 
-  void _emitSnapshotChanged() => _emit("snapshotChanged", createSnapshot());
+  void _emitSnapshotChanged() => _emit(TpsPlaybackEventNames.snapshotChanged, createSnapshot());
 
   int _readLiveElapsedMs() {
     final deltaMs = ((_nowMs() - _playbackStartedAtMs) * playbackRate).round();
@@ -1346,7 +1362,7 @@ class TpsPlaybackSession {
     if (nextStatus == TpsPlaybackStatus.completed && previousStatus == TpsPlaybackStatus.playing) {
       _clearTimer();
     }
-    _emit("statusChanged", {
+    _emit(TpsPlaybackEventNames.statusChanged, {
       "state": currentState,
       "previousStatus": previousStatus,
       "status": nextStatus,
@@ -1363,22 +1379,22 @@ class TpsPlaybackSession {
     currentState = nextState;
     _updateStatus(resolvedStatus);
     if (nextState.currentWord?.id != previousState.currentWord?.id) {
-      _emit("wordChanged", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.wordChanged, {"state": nextState, "previousState": previousState, "status": status});
     }
     if (nextState.currentPhrase?.id != previousState.currentPhrase?.id) {
-      _emit("phraseChanged", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.phraseChanged, {"state": nextState, "previousState": previousState, "status": status});
     }
     if (nextState.currentBlock?.id != previousState.currentBlock?.id) {
-      _emit("blockChanged", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.blockChanged, {"state": nextState, "previousState": previousState, "status": status});
     }
     if (nextState.currentSegment?.id != previousState.currentSegment?.id) {
-      _emit("segmentChanged", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.segmentChanged, {"state": nextState, "previousState": previousState, "status": status});
     }
     if (nextState.elapsedMs != previousState.elapsedMs || status != previousStatus) {
-      _emit("stateChanged", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.stateChanged, {"state": nextState, "previousState": previousState, "status": status});
     }
     if (!previousState.isComplete && resolvedStatus == TpsPlaybackStatus.completed) {
-      _emit("completed", {"state": nextState, "previousState": previousState, "status": status});
+      _emit(TpsPlaybackEventNames.completed, {"state": nextState, "previousState": previousState, "status": status});
     }
     _emitSnapshotChanged();
     return nextState;
@@ -1462,7 +1478,7 @@ class TpsStandalonePlayer {
   VoidCallback on(String eventName, void Function(Object?) listener) => session.on(eventName, listener);
   void off(String eventName, void Function(Object?) listener) => session.off(eventName, listener);
   VoidCallback observeSnapshot(void Function(TpsPlaybackSnapshot) listener, [bool emitCurrent = true]) => session.observeSnapshot(listener, emitCurrent);
-  VoidCallback onSnapshotChanged(void Function(TpsPlaybackSnapshot) listener) => session.on("snapshotChanged", (event) => listener(event as TpsPlaybackSnapshot));
+  VoidCallback onSnapshotChanged(void Function(TpsPlaybackSnapshot) listener) => session.on(TpsPlaybackEventNames.snapshotChanged, (event) => listener(event as TpsPlaybackSnapshot));
   PlayerState play() => session.play();
   PlayerState pause() => session.pause();
   PlayerState stop() => session.stop();
@@ -3561,7 +3577,7 @@ bool _isSpokenWord(_WordSeed word) => word.kind == "word" && word.cleanText.isNo
 int _clamp(int value, int minimum, int maximum) => math.min(math.max(value, minimum), maximum);
 int _clampWpm(int candidate, int fallback) => candidate.isFinite ? _clamp(candidate, TpsSpec.minimumWpm, TpsSpec.maximumWpm) : fallback;
 int _normalizeBaseWpm(int? value) => _clampWpm(value ?? TpsSpec.defaultBaseWpm, TpsSpec.defaultBaseWpm);
-int _normalizeSpeedStep(int? value) => value == null || value <= 0 ? 10 : value;
+int _normalizeSpeedStep(int? value) => value == null || value <= 0 ? TpsPlaybackDefaults.defaultSpeedStepWpm : value;
 int _normalizeSpeedOffset(int baseWpm, int offset) => _clamp(baseWpm + offset, TpsSpec.minimumWpm, TpsSpec.maximumWpm) - baseWpm;
 int _nowMs() => DateTime.now().millisecondsSinceEpoch;
 TpsPlaybackStatus _resolveStatusAfterSeek(TpsPlaybackStatus current, int totalDurationMs, int elapsedMs) {

SDK/java/AGENTS.md

@@ -1,6 +1,59 @@
-# ManagedCode.Tps Java SDK
+# AGENTS.md
+
+Project: SDK Java runtime
+Owned by: ManagedCode.Tps SDK maintainers
+
+Parent: `../../AGENTS.md`
+
+## Purpose
+
+- Own the standalone Java TPS runtime.
+- Keep Java compile, restore, playback, and snapshot behavior aligned with the shared TPS contract.
+
+## Entry Points
+
+- `src/main/java/com/managedcode/tps/ManagedCodeTps.java`
+- `src/test/java/com/managedcode/tps/ManagedCodeTpsTests.java`
+- `build.sh`
+- `test.sh`
+
+## Boundaries
+
+- In scope:
+  - Java runtime implementation
+  - Java runtime test harness and coverage script
+  - parity with the shared fixture set
+- Out of scope:
+  - Android UI integration
+  - non-Java runtime source changes unless parity requires them
+
+## Project Commands
+
+- `build`: `./build.sh`
+- `test`: `./test.sh`
+- `coverage`: `./coverage.sh`
+
+## Applicable Skills
+
+- `mcaf-solid-maintainability`
+- `mcaf-testing`
+- `dotnet-mcaf-documentation`
+
+## Local Risks Or Protected Areas
+
+- Shared fixture parity with `SDK/fixtures/**` and `examples/*.tps` is a protected contract.
+- Public nested types under `ManagedCodeTps` are a stable host-facing API surface.
+- Playback snapshots and event names must remain transport-compatible with the other runtimes.
+
+## Local Rules
 
-- Keep the Java runtime behavior aligned with `SDK/ts`, `SDK/js`, `SDK/dotnet`, `SDK/flutter`, and `SDK/swift`.
-- Validate against `SDK/fixtures/**` and `examples/*.tps`.
 - Keep the runtime embeddable and UI-framework-neutral.
 - Prefer immutable public models and deterministic playback math.
+- Replace meaningful literals with named constants before adding new playback behavior.
+
+## Exception Record
+
+- Size exception:
+  - scope: `src/main/java/com/managedcode/tps/ManagedCodeTps.java`
+  - reason: the Java runtime still ships as a parity-first single source file while the contract is stabilized
+  - removal plan: split into package-level classes for constants, parser, compiler, player, playback session, and compiled transport