Subdirectories

.github/workflows/ci.yml

@@ -41,6 +41,9 @@ jobs:
       - name: Run every pre-commit hook
         run: uv run pre-commit run --all-files --show-diff-on-failure --color always
 
+      - name: Check the committed icons match the mark
+        run: uv run pre-commit run icons --all-files --hook-stage pre-push --color always
+
   tests:
     name: Tests (${{ matrix.os }}, py${{ matrix.python }})
     runs-on: ${{ matrix.os }}

.github/workflows/workflow.yml

@@ -126,7 +126,7 @@ jobs:
             venv_python=.venv-build/bin/python
           fi
           "$venv_python" -m pip install --upgrade pip
-          "$venv_python" -m pip install ".[build]"
+          "$venv_python" -m pip install ".[build]" --group assets
 
       - name: Build the bundle (Linux)
         if: runner.os == 'Linux'

.gitignore

@@ -4,25 +4,20 @@ __pycache__/
 .ipynb_checkpoints/
 .mypy_cache/
 .pytest_cache/
+.ruff_cache/
 .venv/
 .venv-build/
 .vscode/
 
-bin/
-build/
 dist/
 wheels/
-!scripts/**/build/
+/bin/
+/build/
 
 sampletones
 !src/sampletones
 !tests/sampletones
 
-**/*.idea
-**/*.vscode/**
-**/*.ipynb_checkpoints/**
-**/*__pycache__/**
-
 *.pyc
 *.pyo
 *.coverage

.pre-commit-config.yaml

@@ -91,6 +91,16 @@ repos:
         require_serial: true
         exclude: ^(tests/)
 
+      - id: icons
+        name: icons
+        entry: uv run python scripts/assets/icons.py
+        language: system
+        files: ^src/sampletones_assets/(icons|mark)/
+        pass_filenames: false
+        verbose: true
+        stages:
+          - pre-push
+
       - id: pytest
         name: pytest
         entry: make test

CHANGELOG.md

@@ -12,6 +12,7 @@
 * Improved Sequencer module playback.
 * Added song export to WAV/MP3.
 * Added tracker selection operations.
+* Added a _SampleToNES_ logo.
 
 ## v0.3.0 [2026-07-31]
 

LICENSE

@@ -22,7 +22,9 @@ SOFTWARE.
 
 ---
 
-The MIT license above covers the SampleToNES source code only.
+The MIT license above covers the SampleToNES source code and the application
+icons under `src/sampletones_assets/icons/`, which are drawn from the mark
+declared in `src/sampletones_assets/mark/`.
 
 Font files bundled under `src/sampletones_assets/fonts/` are the work of third
 parties and remain under their own licenses (SIL Open Font License 1.1 and the

Makefile

@@ -1,5 +1,5 @@
 .PHONY: help setup install build release system-deps run clean pre-commit test \
-	ftm-samples check-import-boundary check-tag-names check-unused-tags \
+	ftm-samples icons check-import-boundary check-tag-names check-unused-tags \
 	check-language-keys check-palette-colors calibration lint pylint mypy format
 
 ifeq ($(OS),Windows_NT)
@@ -70,6 +70,7 @@ help:
 	@echo $(Q)  make release     - Compile standalone executable with the release deployment config$(Q)
 	@echo $(Q)  make test        - Run unit tests with coverage$(Q)
 	@echo $(Q)  make ftm-samples - Emit example .ftm files to build/ftm via the integration suite$(Q)
+	@echo $(Q)  make icons       - Generate the icon suite into src/sampletones_assets/icons$(Q)
 	@echo $(Q)  make calibration - Score the reconstruction corpus; the report lands in Documents/SampleToNES/calibration$(Q)
 	@echo $(Q)  make clean       - Remove build artifacts and cache files$(Q)
 	@echo $(Q)  make lint        - Run linting (pylint, mypy)$(Q)
@@ -78,6 +79,7 @@ help:
 
 setup:
 	$(SETUP_ENV) uv sync --group dev $(if $(GPU_EXTRA),--extra $(GPU_EXTRA),)
+	$(MAKE) icons
 	$(SETUP_ENV) uv tool install --force $(if $(GPU_EXTRA),".[$(GPU_EXTRA)]",.)
 
 install:
@@ -109,6 +111,9 @@ ftm-samples: export SAMPLETONES_FTM_OUTPUT_DIR := build/ftm
 ftm-samples:
 	uv run python -m pytest tests/integration/famitracker
 
+icons:
+	uv run --group assets python scripts/assets/icons.py
+
 check-import-boundary:
 	uv run scripts/checks/import_boundary.py --all
 

README.md

@@ -4,11 +4,15 @@
 [![Python](https://img.shields.io/pypi/pyversions/sampletones.svg)](https://pypi.org/project/sampletones/)
 [![License](https://img.shields.io/pypi/l/sampletones.svg)](https://github.com/JakimPL/SampleToNES/blob/main/LICENSE)
 
+<div align="center">
+    <img src="https://raw.githubusercontent.com/JakimPL/SampleToNES/main/src/sampletones_assets/icons/sampletones.svg" alt="SampleToNES" width="64">
+</div>
+
 ## Overview
 
 _SampleToNES_ (`sampletones`) is a desktop tool for people writing music for the NES 2A03 sound chip, mainly in [_FamiTracker_](http://famitracker.com/).
 
-<img src="docs/images/sampletones.png" alt="SampleToNES" width="640">
+<img src="https://raw.githubusercontent.com/JakimPL/SampleToNES/main/docs/images/sampletones.png" alt="SampleToNES" width="640">
 
 The core idea is to approximate an audio sample using only the chip's basic oscillators — two pulse channels, a triangle, and noise — **without any DPCM samples**.
 

THIRD-PARTY-NOTICES.md

@@ -109,3 +109,18 @@ The published bundles are **CPU-only**: CuPy, the CUDA runtime and the NVIDIA li
 are proprietary, and their EULA reserves redistribution to NVIDIA. GPU acceleration comes
 from installing _SampleToNES_ from PyPI with the `gpu` extra, which fetches CuPy and the
 CUDA components from their publishers straight to your machine.
+
+## Build-time tooling
+
+The application icons are drawn by `sampletones_assets.mark` and rasterized with
+[Pillow](https://pypi.org/project/Pillow/), which is under the
+[MIT-CMU license](https://github.com/python-pillow/Pillow/blob/main/LICENSE). Pillow belongs
+to the `assets` dependency group alone, so `pip`/`uv` installs it on the machine that
+generates the icons: it stays out of the wheel's dependency set, and PyInstaller is told to
+leave it out of the bundles. Both distributions carry the finished icon files, so Pillow's
+attribution clause — a condition on redistributing Pillow itself — rests with the build
+environment.
+
+The icons (`sampletones.svg`, `sampletones.png` and the multi-resolution `sampletones.ico`)
+are original _SampleToNES_ artwork and fall under the MIT License together with the rest of
+the source.

docs/development/architecture.md

@@ -2,7 +2,7 @@
 
 This document describes the design of `sampletones_application` — the GUI front-end of _SampleToNES_. It is prescriptive: it states the contracts each layer must honour, in the form they are enforced, and the rationale behind them. Use it as the reference when deciding where new code belongs.
 
-Concrete classes and modules appear throughout as **examples** that anchor a rule; the rules bind every instance, named or not. Known deviations from these contracts are tracked in `docs/development/bugs-and-todos.md`. Coding-level rules live in `docs/development/guidelines.md`; the undo subsystem has its own design document, `docs/development/undo.md`, the audio transport has `docs/development/playback.md`, and the YAML configuration package has `docs/development/config-organization.md`.
+Concrete classes and modules appear throughout as **examples** that anchor a rule; the rules bind every instance, named or not. Known deviations from these contracts are tracked in `docs/development/bugs-and-todos.md`. Coding-level rules live in `docs/development/guidelines.md`; the undo subsystem has its own design document, `docs/development/undo.md`, the audio transport has `docs/development/playback.md`, the reconstruction browser has `docs/development/browser.md`, and the YAML configuration package has `docs/development/config-organization.md`.
 
 ---
 
@@ -259,6 +259,8 @@ They read the source as an AST through the shared layer in `sampletones_shared/m
 
 `logic/history/` implements the session-scoped undo engine (`HistoryManager`); its invariants and mechanics are documented in `docs/development/undo.md`.
 
+`logic/reconstruction/browser/` builds the tree of reconstructions both browser tabs render (`BrowserManager`); its pipeline, node vocabulary and shaping rules are documented in `docs/development/browser.md`.
+
 **Contracts:**
 - Logic classes produce view models and may therefore import `view_model/`; they import neither `ui/` nor `coordinators/`.
 - Logic classes never call DPG.