Merge pull request #3 from hooshyar/agent/dot-finish/s1

feat: 1.1.0 prep: sizing, reduced motion, customDotSize, AI presets, green CI

Author: hooshyar

.github/workflows/ci.yml

@@ -7,6 +7,27 @@ on:
     branches: [main]
 
 jobs:
+  portable-filenames:
+    name: Windows-safe tracked file names
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Fail on paths Windows cannot check out
+        # A backlog file with `"` and `:` in its name made
+        # `git pull` fail for every Windows user. Reject <>:"\|?* , a trailing
+        # space or dot, and reserved device names in any tracked path.
+        run: |
+          bad="$(git -c core.quotepath=off ls-files | grep -E '[<>:"\\|?*]|[ .]$|(^|/)(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^/]*)?(/|$)' || true)"
+          if [ -n "$bad" ]; then
+            echo "::error::Tracked paths that Windows cannot create:"
+            echo "$bad"
+            exit 1
+          fi
+          echo "All tracked paths are Windows-safe."
+
   analyze-and-test:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -33,3 +33,4 @@ migrate_working_dir/
 # Claude Code local session state
 .claude/scheduled_tasks.lock
 .claude/settings.local.json
+.claude/agent-memory/

.pubignore

@@ -9,6 +9,11 @@
 /SPECS.md
 /tool/
 /doc/
+/docs/
+/backlog/
+
+# README hero GIFs are referenced by absolute raw.githubusercontent.com URLs.
+*.gif
 
 # --- Mirror of .gitignore patterns we still want excluded from pub ---
 # (When .pubignore is present, it fully replaces .gitignore for archive

AGENTS.md

@@ -41,6 +41,14 @@ import 'package:flutter_dot_loader/flutter_dot_loader.dart';
 const DotLoader(color: Colors.blue)
 ```
 
+Pick a named state when the chat state is known: `DotLoader.typing()`,
+`DotLoader.thinking()`, `DotLoader.searching()`, `DotLoader.generating()`
+(each takes `color`, `size`/`width`/`height`, `paused`, `semanticsLabel`).
+The box is only as tall as the dots, so it sits inline next to text. All
+loaders honour the OS reduced-motion setting (`respectReducedMotion`, default
+true) and `MatrixLoader` accepts `customDotSize: (row, col) => scale` for
+per-dot sizing.
+
 That's it. No size tuning, no opacity tuning, no animation knobs. Wrap in a
 `SizedBox` only if the parent layout needs a tighter bound.
 

CHANGELOG.md

@@ -1,3 +1,36 @@
+## 1.1.0
+
+- feat: `width` and `height` on `MatrixLoader`, `DotLoader`, and
+  `TriangleLoader`. `size` remains as the square shorthand and existing call
+  sites render identically; each new parameter falls back to `size` when not
+  set.
+- fix: auto dot spacing is now computed per axis, so grids with
+  `rows > columns` (for example `columns: 1, rows: 5, size: 64`) no longer
+  paint outside the widget's bounding box. Tap hit-testing shares the same
+  geometry.
+- feat: `DotLoader` derives its box height from `rows` and `dotSize` when
+  `height` is not given, so the default 3x1 indicator takes a
+  text-height-friendly box instead of a 64x64 square. Pass `height` to
+  restore an explicit box.
+- fix: `MatrixShape.triangle` no longer divides by zero on 1-row or 1-column
+  grids (previously the mask produced NaN comparisons and rendered nothing).
+- feat: `respectReducedMotion` (default `true`) on `MatrixLoader`, `DotLoader`
+  and `TriangleLoader`. When `MediaQuery.disableAnimationsOf` is true the
+  ticker stops and one static frame is painted (the end frame for
+  `MatrixPlayback.once`, which fires `onComplete` once). Reacts to runtime
+  changes of the setting.
+- feat: `customDotSize: double Function(int row, int col)?` on `MatrixLoader`
+  and `DotLoader` scales or hides individual dots (answers issue #1). Painting
+  only; hit-testing and auto-spacing keep using `dotSize`.
+- feat: AI-state presets `DotLoader.typing()`, `.thinking()`, `.searching()`
+  and `.generating()` with curated grids, patterns, durations and default
+  semantics labels.
+- docs: CI badge, "Works great with" chat-bubble recipe, README alias count
+  (16), hero GIFs referenced by absolute URL and excluded from the pub
+  archive, pubspec boilerplate removed, dart format drift fixed (CI green again).
+- test: widget coverage for `rows > columns`, 1xN, Nx1, and 1-row triangle
+  grids asserting painted bounds stay inside the widget.
+
 ## 1.0.0
 
 First stable release. The API surface (`MatrixLoader`, `DotLoader`,

README.md

@@ -1,5 +1,6 @@
 # flutter_dot_loader
 
+[![CI](https://github.com/hooshyar/flutter_dot_loader/actions/workflows/ci.yml/badge.svg)](https://github.com/hooshyar/flutter_dot_loader/actions/workflows/ci.yml)
 [![pub.dev](https://img.shields.io/pub/v/flutter_dot_loader.svg?style=flat-square&color=ff3333&label=pub.dev)](https://pub.dev/packages/flutter_dot_loader)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Flutter](https://img.shields.io/badge/Flutter-%E2%9D%A4-02569B?style=flat-square&logo=flutter)](https://flutter.dev)
@@ -12,8 +13,8 @@ From a 3-dot "thinking…" indicator for AI chats to a 60-pattern LED matrix wit
 ### ▶️ [Try the live demo](https://hooshyar.github.io/flutter_dot_loader/) — browse all 60 patterns, tweak every knob, and draw your own frames right in the browser.
 
 <p align="center">
-  <img src="assets/1.gif" width="48%" alt="Gallery of 60 dot-matrix loader patterns" />
-  <img src="assets/2.gif" width="48%" alt="Interactive Dot Matrix Studio editor" />
+  <img src="https://raw.githubusercontent.com/hooshyar/flutter_dot_loader/main/assets/1.gif" width="48%" alt="Gallery of 60 dot-matrix loader patterns" />
+  <img src="https://raw.githubusercontent.com/hooshyar/flutter_dot_loader/main/assets/2.gif" width="48%" alt="Interactive Dot Matrix Studio editor" />
 </p>
 
 ---
@@ -23,7 +24,7 @@ From a 3-dot "thinking…" indicator for AI chats to a 60-pattern LED matrix wit
 | Feature | Description |
 |---|---|
 | 💬 **AI-chat "thinking" indicator** | One-liner `DotLoader(color: …)` for chat / AI apps — sensible defaults, `const`-constructable |
-| 🎨 **60 Built-in Patterns** | 20 Square, 20 Circular, and 20 Triangle math-driven animations + 13 semantic aliases (`vortexSpin`, `bullsEye`, `coreRipple`…) |
+| 🎨 **60 Built-in Patterns** | 20 Square, 20 Circular, and 20 Triangle math-driven animations + 16 semantic aliases (`vortexSpin`, `bullsEye`, `coreRipple`…) |
 | 🖥️ **LED Dot-Matrix Feel** | Three-tier opacity remapping for a realistic glowing LED display effect |
 | 🧩 **Custom Frames** | Drive every dot from your own data (`customIntensity`) — sprites, Tetris, scrolling text |
 | 📝 **Scrolling Marquee Text** | Built-in 5×7 font covers A–Z, 0–9, and 30+ punctuation/symbols (e.g. `"LOADING: 42%"`, `"a@b.com"`) |
@@ -67,7 +68,7 @@ Add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  flutter_dot_loader: ^1.0.0
+  flutter_dot_loader: ^1.1.0
 ```
 
 Or run:
@@ -95,7 +96,36 @@ const DotLoader(color: Colors.blue)
 ```
 
 3 dots, horizontal wave, 1.5s cycle. Inactive color is automatically derived
-from the supplied color at 10% alpha.
+from the supplied color at 10% alpha. The box is only as tall as the dots, so it
+sits inline next to text; pass `width`/`height` to change it.
+
+Name the state instead of picking a pattern:
+
+```dart
+const DotLoader.thinking(color: Colors.blue)    // calm 3-dot ribbon
+const DotLoader.searching(color: Colors.blue)   // 5-dot scanner sweep
+const DotLoader.generating(color: Colors.blue)  // quick 5-dot wave
+const DotLoader.typing(color: Colors.blue)      // classic 3-dot wave
+```
+
+### Works great with
+
+Drop a `DotLoader` into a chat bubble while a reply is on its way, then swap in
+streamed text from [`flutter_streaming_text_markdown`](https://pub.dev/packages/flutter_streaming_text_markdown)
+or a full chat screen from [`flutter_gen_ai_chat_ui`](https://pub.dev/packages/flutter_gen_ai_chat_ui):
+
+```dart
+Container(
+  padding: const EdgeInsets.symmetric(horizontal: 14, vertical: 12),
+  decoration: BoxDecoration(
+    color: Theme.of(context).colorScheme.surfaceContainerHighest,
+    borderRadius: BorderRadius.circular(16),
+  ),
+  child: waitingForFirstToken
+      ? DotLoader.thinking(color: Theme.of(context).colorScheme.primary)
+      : StreamingTextMarkdown.chatGPT(text: reply),
+)
+```
 
 ### 1. Drop-in Loader
 
@@ -188,7 +218,9 @@ const DotLoader(
 )
 ```
 
-Available on `MatrixLoader`, `DotLoader`, and `TriangleLoader`; follows the same convention as Flutter's `ProgressIndicator.semanticsLabel`.
+Available on `MatrixLoader`, `DotLoader`, and `TriangleLoader`; follows the same convention as Flutter's `ProgressIndicator.semanticsLabel`. The `DotLoader.typing/thinking/searching/generating` presets ship with a default label.
+
+**Reduced motion.** When the OS "reduce motion" setting is on (`MediaQuery.disableAnimations`), every loader stops its ticker and paints one static frame (the end frame for `MatrixPlayback.once`, which also fires `onComplete` right away). It reacts if the setting changes while the app runs. Opt out per widget with `respectReducedMotion: false`.
 
 ### 5. Pick from 60 Patterns
 
@@ -341,14 +373,18 @@ The primary widget for dot-matrix loading animations.
 | `pattern` | `MatrixPattern` | `square1` | Animation pattern; use `custom` with `customIntensity` |
 | `activeColor` | `Color` | `Colors.white` | Color of lit/active dots |
 | `inactiveColor` | `Color` | `Color(0xFF27272A)` | Color of dim/inactive dots |
-| `size` | `double` | `64.0` | Width and height of the bounding box |
+| `size` | `double` | `64.0` | Square bounding-box shorthand; fallback for `width`/`height` |
+| `width` | `double?` | `null` | Bounding box width; falls back to `size` when `null` |
+| `height` | `double?` | `null` | Bounding box height; falls back to `size` when `null` (`DotLoader` derives it from `rows` instead) |
 | `dotSize` | `double` | `4.0` | Diameter of each dot in logical pixels |
-| `spacing` | `double?` | auto | Gap between dots; auto-calculated from `size` if `null` |
+| `spacing` | `double?` | auto | Gap between dots; auto-calculated per axis to fit the box if `null` |
 | `duration` | `Duration` | `1500ms` | Duration of one complete animation cycle |
 | `hoverAnimated` | `bool` | `true` | Enables hover ripple on web/desktop |
 | `opacityBase` | `double` | `0.08` | Minimum opacity for unlit dots |
 | `opacityMid` | `double` | `0.34` | Mid-point opacity for the LED glow curve |
 | `opacityPeak` | `double` | `0.94` | Maximum opacity for fully lit dots |
+| `customDotSize` | `double Function(int row, int col)?` | `null` | Per-dot size scale (1.0 = `dotSize`, 0 hides the dot). Painting only: tap hit-testing and auto-spacing keep using `dotSize` |
+| `respectReducedMotion` | `bool` | `true` | Stop animating and paint one static frame when the OS asks for reduced motion |
 | `customMask` | `bool Function(int row, int col)?` | `null` | Custom function to determine if a dot is rendered |
 | `customIntensity` | `double Function(int row, int col, double progress)?` | `null` | Custom function to drive dot intensity (use with `MatrixPattern.custom`) |
 | `semanticsLabel` | `String?` | `null` | Label announced by screen readers; `null` = decorative (no semantics node) |
@@ -387,7 +423,10 @@ A geometric loader using a tessellated grid of equilateral triangles.
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `color` | `Color` | `Colors.indigoAccent` | Color of the triangles |
-| `size` | `double` | `200.0` | Width and height of the bounding box |
+| `size` | `double` | `200.0` | Square bounding-box shorthand; fallback for `width`/`height` |
+| `width` | `double?` | `null` | Bounding box width; falls back to `size` when `null` |
+| `height` | `double?` | `null` | Bounding box height; falls back to `size` when `null` |
+| `respectReducedMotion` | `bool` | `true` | Stop animating and paint one static frame when the OS asks for reduced motion |
 | `triangleSize` | `double` | `30.0` | Side length of each equilateral triangle |
 | `duration` | `Duration` | `4s` | Duration of one animation cycle |
 | `wireframe` | `bool` | `false` | If `true`, renders only triangle outlines |

analysis_options.yaml

@@ -10,6 +10,8 @@ analyzer:
   errors:
     deprecated_member_use: warning
     deprecated_member_use_from_same_package: warning
+  exclude:
+    - build/**
 
 linter:
   rules:

backlog/tasks/task-001 - Fix red CI on main (dart format drift).md

@@ -1,7 +1,7 @@
 ---
 id: TASK-001
 title: Fix red CI on main (dart format drift)
-status: To Do
+status: Done
 priority: high
 labels: [improvement-plan-2026-09]
 created_date: '2026-09-24'
@@ -19,3 +19,7 @@ Acceptance criteria:
 - [ ] Ship as 1.0.1
 
 See docs/IMPROVEMENT-PLAN-2026-09.md (P0-1, B1, B5, B6).
+
+## Final Summary
+
+Formatting fixed with the resolved package config, CI badge and README alias count (16) added, pubspec boilerplate removed. Included in 1.1.0 rather than a separate 1.0.1.

backlog/tasks/task-002 - Honor reduced motion (MediaQuery.disableAnimations).md

@@ -1,7 +1,7 @@
 ---
 id: TASK-002
 title: Honor reduced motion (MediaQuery.disableAnimations)
-status: To Do
+status: Done
 priority: high
 labels: [improvement-plan-2026-09]
 created_date: '2026-09-24'
@@ -18,3 +18,7 @@ Acceptance criteria:
 - [ ] Widget tests for on/off; README a11y row + CHANGELOG updated
 
 See docs/IMPROVEMENT-PLAN-2026-09.md (P0-2).
+
+## Final Summary
+
+`respectReducedMotion` (default true) on MatrixLoader, DotLoader and TriangleLoader with runtime reaction and tests. Ships in 1.1.0.

…fix grid overflow when rows > columns.md …- non-square-sizing-and-grid-overflow.mdbacklog/tasks/task-003 - Non-square sizing and fix grid overflow when rows > columns.md renamed to backlog/tasks/task-003 - non-square-sizing-and-grid-overflow.md backlog/tasks/task-003 - Non-square sizing and fix grid overflow when rows > columns.md renamed to backlog/tasks/task-003 - non-square-sizing-and-grid-overflow.md

@@ -1,7 +1,7 @@
 ---
 id: TASK-003
 title: Non-square sizing and fix grid overflow when rows > columns
-status: To Do
+status: Done
 priority: high
 labels: [improvement-plan-2026-09]
 created_date: '2026-09-24'
@@ -20,3 +20,7 @@ Acceptance criteria:
 - [ ] Ship in 1.1.0
 
 See docs/IMPROVEMENT-PLAN-2026-09.md (P0-3, B2, B3).
+
+## Final Summary
+
+`width`/`height` with `size` shorthand, per-axis spacing, shared tap geometry, inline DotLoader box (default 64x4), triangle mask fix, tests. Ships in 1.1.0.