main.js

/**
 * CategoryDiffusion — Wikimedia Commons user script
 *
 * Helps editors diffuse overfull categories by suggesting appropriate
 * subcategories for each file, using an LLM via a Cloudflare Worker proxy.
 *
 * All Commons API work (tree crawl, file metadata) runs in the browser.
 * Only LLM calls go through the external Worker.
 *
 * Install: add the following to your common.js on Commons:
 *   importScript('User:Alaexis/Diffusor.js');
 */
( function () {
	'use strict';

	// -----------------------------------------------------------------------
	// Configuration
	// -----------------------------------------------------------------------
	var CONFIG = {
		// URL of your Cloudflare Worker that proxies LLM requests
		llmProxyUrl: 'https://publicai-proxy.alaexis.workers.dev/hf',
		llmModel: 'openai/gpt-oss-20b',
		// gpt-oss is a reasoning model: reasoning tokens count against
		// max_tokens, and at the default effort it often loops over the long
		// category list until the budget runs out, returning no JSON at all.
		llmMaxTokens: 8192,
		llmReasoningEffort: 'low',
		llmTemperature: 0.1,

		// Subcategory tree crawl limits
		maxTreeDepth: 5,
		maxTreeNodes: 2000,

		// LLM batching
		filesPerBatch: 20,
		maxFilesPerCategory: 500,

		// UI
		panelWidth: '420px',
		localStoragePrefix: 'catdiffusion-'
	};

	// Allow user overrides
	if ( window.CategoryDiffusionConfig ) {
		$.extend( CONFIG, window.CategoryDiffusionConfig );
	}

	// -----------------------------------------------------------------------
	// State
	// -----------------------------------------------------------------------
	var state = {
		categoryTitle: mw.config.get( 'wgPageName' ),
		analysisStatus: 'idle',   // idle | running | done | error
		suggestions: {},          // { "File:Foo.jpg": ["Cat1","Cat2"], ... }
		reviewedFiles: {},        // { "File:Foo.jpg": true, ... }
		currentFile: null,        // file title currently shown in panel
		subcategories: [],        // flat list of subcategory titles (without "Category:")
		fileMetadata: {},         // { "File:Foo.jpg": { description, categories }, ... }
		customCategories: [],     // categories the user added by hand, offered for every file
		failedBatches: 0,         // LLM batches that returned no usable JSON
		totalBatches: 0
	};

	// -----------------------------------------------------------------------
	// CSS
	// -----------------------------------------------------------------------
	function injectStyles() {
		var css = [

			/* Per-thumbnail suggest buttons */
			'.catdiff-suggest-btn {',
			'  display: inline-block;',
			'  margin-top: 4px;',
			'  padding: 2px 8px;',
			'  font-size: 11px;',
			'  background: #36c;',
			'  color: #fff;',
			'  border: none;',
			'  border-radius: 3px;',
			'  cursor: pointer;',
			'}',
			'.catdiff-suggest-btn:hover { background: #2a4b8d; }',
			'.catdiff-suggest-btn:disabled {',
			'  background: #aaa;',
			'  cursor: not-allowed;',
			'}',
			'.catdiff-suggest-btn.catdiff-reviewed {',
			'  background: #72777d;',
			'}',
			'.catdiff-suggest-btn.catdiff-reviewed::after {',
			'  content: " \\2713";',
			'}',
			'.catdiff-suggest-btn.catdiff-has-suggestions {',
			'  background: #14866d;',
			'}',

			/* Gallery item reviewed overlay */
			'.catdiff-gallery-reviewed {',
			'  opacity: 0.55;',
			'}',

			/* Right-side panel */
			'#catdiff-panel {',
			'  display: none;',
			'  position: fixed;',
			'  top: 0;',
			'  right: 0;',
			'  width: ' + CONFIG.panelWidth + ';',
			'  height: 100vh;',
			'  background: #fff;',
			'  border-left: 2px solid #a2a9b1;',
			'  box-shadow: -3px 0 12px rgba(0,0,0,0.15);',
			'  z-index: 10000;',
			'  overflow-y: auto;',
			'  padding: 16px;',
			'  box-sizing: border-box;',
			'  font-size: 13px;',
			'}',
			'#catdiff-panel.catdiff-panel-open {',
			'  display: block;',
			'}',

			/* Panel header */
			'#catdiff-panel-close {',
			'  float: right;',
			'  background: none;',
			'  border: none;',
			'  font-size: 20px;',
			'  cursor: pointer;',
			'  color: #555;',
			'  line-height: 1;',
			'}',
			'#catdiff-panel-close:hover { color: #d33; }',

			'#catdiff-panel h3 {',
			'  margin: 0 0 12px 0;',
			'  font-size: 15px;',
			'  border-bottom: 1px solid #c8ccd1;',
			'  padding-bottom: 8px;',
			'}',

			/* Panel thumbnail */
			'#catdiff-panel-thumb {',
			'  max-width: 100%;',
			'  max-height: 200px;',
			'  display: block;',
			'  margin: 8px auto;',
			'  border: 1px solid #c8ccd1;',
			'}',

			/* Panel sections */
			'.catdiff-section {',
			'  margin: 12px 0;',
			'}',
			'.catdiff-section-title {',
			'  font-weight: bold;',
			'  margin-bottom: 4px;',
			'  color: #222;',
			'}',

			/* Description */
			'#catdiff-description {',
			'  max-height: 120px;',
			'  overflow-y: auto;',
			'  background: #f8f9fa;',
			'  padding: 6px 8px;',
			'  border-radius: 3px;',
			'  font-size: 12px;',
			'  white-space: pre-wrap;',
			'  word-break: break-word;',
			'}',

			/* Current categories list */
			'#catdiff-current-cats {',
			'  list-style: none;',
			'  padding: 0;',
			'  margin: 4px 0;',
			'}',
			'#catdiff-current-cats li {',
			'  padding: 2px 0;',
			'  color: #555;',
			'  font-size: 12px;',
			'}',
			'#catdiff-current-cats li::before {',
			'  content: "\\2022 ";',
			'  color: #999;',
			'}',

			/* Suggested categories checkboxes */
			'#catdiff-suggestions-list {',
			'  list-style: none;',
			'  padding: 0;',
			'  margin: 4px 0;',
			'}',
			'#catdiff-suggestions-list li {',
			'  padding: 3px 0;',
			'}',
			'#catdiff-suggestions-list label {',
			'  cursor: pointer;',
			'}',
			'#catdiff-suggestions-list label.catdiff-already-present,',
			'#catdiff-custom-list label.catdiff-already-present {',
			'  color: #999;',
			'  text-decoration: line-through;',
			'}',

			/* User-added categories */
			'#catdiff-custom-list {',
			'  list-style: none;',
			'  padding: 0;',
			'  margin: 4px 0;',
			'}',
			'#catdiff-custom-list li {',
			'  padding: 3px 0;',
			'}',
			'#catdiff-custom-list label {',
			'  cursor: pointer;',
			'}',
			'#catdiff-custom-list li.catdiff-custom-hint {',
			'  font-size: 11px;',
			'  color: #72777d;',
			'}',
			'.catdiff-custom-remove {',
			'  background: none;',
			'  border: none;',
			'  color: #999;',
			'  cursor: pointer;',
			'  font-size: 14px;',
			'  padding: 0 4px;',
			'}',
			'.catdiff-custom-remove:hover { color: #d33; }',
			'#catdiff-custom-form {',
			'  display: flex;',
			'  gap: 6px;',
			'  margin-top: 6px;',
			'}',
			'#catdiff-custom-input {',
			'  flex: 1;',
			'  min-width: 0;',
			'  padding: 4px 6px;',
			'  font-size: 13px;',
			'  border: 1px solid #a2a9b1;',
			'  border-radius: 3px;',
			'}',
			'#catdiff-custom-add {',
			'  padding: 4px 12px;',
			'  background: #fff;',
			'  color: #36c;',
			'  font-weight: bold;',
			'  border: 1px solid #36c;',
			'  border-radius: 3px;',
			'  cursor: pointer;',
			'  font-size: 13px;',
			'}',
			'#catdiff-custom-add:hover { background: #eaf3ff; }',
			'#catdiff-custom-add:disabled {',
			'  color: #72777d;',
			'  border-color: #c8ccd1;',
			'  background: #fff;',
			'  cursor: default;',
			'}',
			'#catdiff-custom-status {',
			'  font-size: 11px;',
			'  color: #72777d;',
			'  margin-top: 4px;',
			'}',
			'#catdiff-custom-status.catdiff-error {',
			'  color: #d33;',
			'}',

			/* Suggestion count */
			'#catdiff-suggestion-count {',
			'  font-size: 11px;',
			'  color: #72777d;',
			'  margin-top: 4px;',
			'}',

			/* Panel action buttons */
			'.catdiff-actions {',
			'  margin-top: 16px;',
			'  display: flex;',
			'  gap: 8px;',
			'}',
			'.catdiff-btn-accept {',
			'  flex: 1;',
			'  padding: 8px;',
			'  background: #14866d;',
			'  color: #fff;',
			'  font-weight: bold;',
			'  border: none;',
			'  border-radius: 4px;',
			'  cursor: pointer;',
			'  font-size: 13px;',
			'}',
			'.catdiff-btn-accept:hover { background: #0d6b56; }',
			'.catdiff-btn-accept:disabled, .catdiff-btn-accept:disabled:hover {',
			'  background: #c8ccd1;',
			'  color: #72777d;',
			'  cursor: default;',
			'}',
			'.catdiff-btn-reject {',
			'  flex: 1;',
			'  padding: 8px;',
			'  background: #fff;',
			'  color: #555;',
			'  font-weight: bold;',
			'  border: 1px solid #a2a9b1;',
			'  border-radius: 4px;',
			'  cursor: pointer;',
			'  font-size: 13px;',
			'}',
			'.catdiff-btn-reject:hover { background: #f0f0f0; }',
			'.catdiff-btn-review {',
			'  flex: 1;',
			'  padding: 8px;',
			'  background: #fff;',
			'  color: #36c;',
			'  font-weight: bold;',
			'  border: 1px solid #36c;',
			'  border-radius: 4px;',
			'  cursor: pointer;',
			'  font-size: 13px;',
			'}',
			'.catdiff-btn-review:hover { background: #eaf3ff; }',

			/* Loading spinner */
			'.catdiff-loading {',
			'  text-align: center;',
			'  padding: 24px;',
			'  color: #72777d;',
			'}',

			/* Progress status */
			'#catdiff-progress-status {',
			'  margin: 8px 0;',
			'  line-height: 1.5;',
			'  color: #222;',
			'}',
			'#catdiff-progress-stages {',
			'  margin-top: 12px;',
			'}',

			/* Push content left when panel is open */
			'body.catdiff-panel-active #mw-content-text {',
			'  margin-right: ' + CONFIG.panelWidth + ';',
			'}'
		].join( '\n' );

		$( '<style>' ).text( css ).appendTo( 'head' );
	}

	// -----------------------------------------------------------------------
	// LocalStorage helpers
	// -----------------------------------------------------------------------
	function getStorageKey( suffix ) {
		return CONFIG.localStoragePrefix + state.categoryTitle + '-' + suffix;
	}

	function loadReviewedState() {
		try {
			var raw = localStorage.getItem( getStorageKey( 'reviewed' ) );
			if ( raw ) {
				state.reviewedFiles = JSON.parse( raw );
			}
		} catch ( e ) {
			state.reviewedFiles = {};
		}
	}

	function saveReviewedState() {
		try {
			localStorage.setItem(
				getStorageKey( 'reviewed' ),
				JSON.stringify( state.reviewedFiles )
			);
		} catch ( e ) {
			// localStorage may be full or unavailable
		}
	}

	function loadCachedSuggestions() {
		try {
			var raw = localStorage.getItem( getStorageKey( 'suggestions' ) );
			if ( raw ) {
				var parsed = JSON.parse( raw );
				state.suggestions = parsed.suggestions || {};
				state.subcategories = parsed.subcategories || [];
				state.fileMetadata = parsed.fileMetadata || {};
				state.analysisStatus = 'done';
				return true;
			}
		} catch ( e ) {
			// ignore
		}
		return false;
	}

	function saveCachedSuggestions() {
		try {
			localStorage.setItem(
				getStorageKey( 'suggestions' ),
				JSON.stringify( {
					suggestions: state.suggestions,
					subcategories: state.subcategories,
					fileMetadata: state.fileMetadata
				} )
			);
		} catch ( e ) {
			// ignore
		}
	}

	function loadCustomCategories() {
		try {
			var raw = localStorage.getItem( getStorageKey( 'custom' ) );
			if ( raw ) {
				state.customCategories = JSON.parse( raw ) || [];
			}
		} catch ( e ) {
			state.customCategories = [];
		}
	}

	function saveCustomCategories() {
		try {
			localStorage.setItem(
				getStorageKey( 'custom' ),
				JSON.stringify( state.customCategories )
			);
		} catch ( e ) {
			// ignore
		}
	}

	// -----------------------------------------------------------------------
	// Commons API: subcategory tree crawl
	// -----------------------------------------------------------------------
	function fetchDirectSubcategories( categoryTitle ) {
		var api = new mw.Api();
		var allSubcats = [];

		function fetchPage( cmcontinue ) {
			var params = {
				action: 'query',
				list: 'categorymembers',
				cmtitle: categoryTitle,
				cmtype: 'subcat',
				cmlimit: 500,
				format: 'json'
			};
			if ( cmcontinue ) {
				params.cmcontinue = cmcontinue;
			}
			return api.get( params ).then( function ( data ) {
				var members = data.query.categorymembers || [];
				var i, len;
				for ( i = 0, len = members.length; i < len; i++ ) {
					allSubcats.push( members[ i ].title );
				}
				if ( data[ 'continue' ] && data[ 'continue' ].cmcontinue ) {
					return fetchPage( data[ 'continue' ].cmcontinue );
				}
				return allSubcats;
			} );
		}

		return fetchPage( null );
	}

	function crawlSubcategoryTree() {
		var deferred = $.Deferred();
		var allSeen = {};
		var currentLevel = [ state.categoryTitle ];
		var depth = 0;

		function processLevel() {
			depth++;
			if ( depth > CONFIG.maxTreeDepth || currentLevel.length === 0 ) {
				var result = Object.keys( allSeen );
				result.sort();
				deferred.resolve( result );
				return;
			}

			var nextLevel = [];
			var idx = 0;
			var total = currentLevel.length;

			function processNext() {
				if ( idx >= total ) {
					currentLevel = nextLevel;
					updateStatus(
						'Depth ' + depth + ' done: ' +
						Object.keys( allSeen ).length + ' subcategories found…'
					);
					processLevel();
					return;
				}

				var cat = currentLevel[ idx ];
				idx++;

				updateStatus(
					'Depth ' + depth + ': expanding ' + idx + '/' + total +
					' (' + Object.keys( allSeen ).length + ' subcats so far)…'
				);

				fetchDirectSubcategories( cat ).then( function ( subcats ) {
					var i, len, s;
					for ( i = 0, len = subcats.length; i < len; i++ ) {
						s = subcats[ i ];
						if ( !allSeen[ s ] && s !== state.categoryTitle ) {
							allSeen[ s ] = true;
							nextLevel.push( s );
							if ( Object.keys( allSeen ).length >= CONFIG.maxTreeNodes ) {
								currentLevel = [];
								var result = Object.keys( allSeen );
								result.sort();
								deferred.resolve( result );
								return;
							}
						}
					}
					processNext();
				}, function ( err ) {
					// Skip failures, continue
					mw.log.warn( 'CategoryDiffusion: failed to expand ' + cat, err );
					processNext();
				} );
			}

			processNext();
		}

		processLevel();
		return deferred.promise();
	}

	// -----------------------------------------------------------------------
	// Commons API: file listing + metadata
	// -----------------------------------------------------------------------
	function fetchCategoryFiles() {
		var api = new mw.Api();
		var allFiles = [];

		function fetchPage( cmcontinue ) {
			var params = {
				action: 'query',
				list: 'categorymembers',
				cmtitle: state.categoryTitle,
				cmtype: 'file',
				cmlimit: 500,
				format: 'json'
			};
			if ( cmcontinue ) {
				params.cmcontinue = cmcontinue;
			}
			return api.get( params ).then( function ( data ) {
				var members = data.query.categorymembers || [];
				var i, len;
				for ( i = 0, len = members.length; i < len; i++ ) {
					allFiles.push( members[ i ].title );
				}
				if ( allFiles.length >= CONFIG.maxFilesPerCategory ) {
					allFiles = allFiles.slice( 0, CONFIG.maxFilesPerCategory );
					return allFiles;
				}
				if ( data[ 'continue' ] && data[ 'continue' ].cmcontinue ) {
					return fetchPage( data[ 'continue' ].cmcontinue );
				}
				return allFiles;
			} );
		}

		return fetchPage( null );
	}

	function fetchFileDescriptions( fileTitles ) {
		var api = new mw.Api();
		var result = {};
		var chunks = [];
		var i;

		// Split into chunks of 50 (MediaWiki API limit)
		for ( i = 0; i < fileTitles.length; i += 50 ) {
			chunks.push( fileTitles.slice( i, i + 50 ) );
		}

		var chunkIdx = 0;

		function processChunk() {
			if ( chunkIdx >= chunks.length ) {
				return $.Deferred().resolve( result ).promise();
			}

			var chunk = chunks[ chunkIdx ];
			chunkIdx++;

			updateStatus(
				'Fetching file metadata: batch ' + chunkIdx + '/' + chunks.length + '…'
			);

			return api.post( {
				action: 'query',
				titles: chunk.join( '|' ),
				prop: 'revisions|categories',
				rvprop: 'content',
				rvslots: 'main',
				cllimit: 'max',
				format: 'json'
			} ).then( function ( data ) {
				var pages = data.query.pages || {};
				var pageId, page, title, wikitext, rev, cats, j, jLen;

				for ( pageId in pages ) {
					if ( !pages.hasOwnProperty( pageId ) || pageId === '-1' ) {
						continue;
					}
					page = pages[ pageId ];
					title = page.title || '';
					if ( !title ) {
						continue;
					}

					// Extract wikitext
					wikitext = '';
					if ( page.revisions && page.revisions[ 0 ] ) {
						rev = page.revisions[ 0 ];
						if ( rev.slots && rev.slots.main ) {
							wikitext = rev.slots.main[ '*' ] || rev.slots.main.content || '';
						} else if ( rev[ '*' ] ) {
							wikitext = rev[ '*' ];
						}
					}

					// Extract categories
					cats = [];
					if ( page.categories ) {
						for ( j = 0, jLen = page.categories.length; j < jLen; j++ ) {
							cats.push( page.categories[ j ].title.replace( /^Category:/, '' ) );
						}
					}

					result[ title ] = {
						description: extractDescription( wikitext ),
						categories: cats
					};
				}

				return processChunk();
			}, function () {
				// Skip failed chunk
				return processChunk();
			} );
		}

		return processChunk();
	}

	function extractDescription( wikitext ) {
		// Try |description= from the Information template
		var match = wikitext.match(
			/\|\s*[Dd]escription\s*=\s*([\s\S]*?)(?=\n\s*\||\n\s*\}\})/m
		);
		if ( match ) {
			var desc = match[ 1 ].trim();
			desc = desc.replace( /\{\{[^}]*\}\}/g, '' );
			desc = desc.replace( /\[\[(?:[^\]|]*\|)?([^\]]*)\]\]/g, '$1' );
			desc = desc.replace( /'''?/g, '' );
			desc = desc.replace( /\s+/g, ' ' ).trim();
			if ( desc ) {
				return desc.substring( 0, 500 );
			}
		}
		// Fallback: first meaningful line
		var lines = wikitext.split( '\n' );
		var i, len, line;
		for ( i = 0, len = lines.length; i < len; i++ ) {
			line = lines[ i ].trim();
			if ( line && !line.match( /^\s*[\[{|!=<]/ ) && line.length > 10 ) {
				return line.substring( 0, 300 );
			}
		}
		return '';
	}

	// -----------------------------------------------------------------------
	// LLM: build prompt, call Worker, parse response
	// -----------------------------------------------------------------------
	function buildLLMPrompt( subcatNames, fileBatch ) {
		var catDisplay = state.categoryTitle.replace( /^Category:/, '' );
		var subcatList = subcatNames.join( '\n' );

		var filesSection = [];
		var i, len, f, name, desc, cats;
		for ( i = 0, len = fileBatch.length; i < len; i++ ) {
			f = fileBatch[ i ];
			name = f.title.replace( /^File:/, '' );
			desc = f.description || '(no description)';
			cats = f.categories.length ? f.categories.join( ', ' ) : '(none)';
			filesSection.push(
				( i + 1 ) + '. Name: ' + name + '\n' +
				'   Description: ' + desc + '\n' +
				'   Current categories: ' + cats
			);
		}

		return 'You are helping categorize Wikimedia Commons files. The category ' +
			'"' + catDisplay + '" needs to be diffused — files should be moved to ' +
			'more specific subcategories.\n\n' +
			'Here are ALL available subcategories (within ' + CONFIG.maxTreeDepth +
			' levels of depth):\n' +
			subcatList + '\n\n' +
			'For each file below, pick 3-5 categories from the above list that ' +
			'best fit the file. Only pick categories from the list above. ' +
			'If none of the listed categories fit well, return an empty list for that file.\n\n' +
			'Output ONLY valid JSON in this exact format, using the file numbers below as keys:\n' +
			'{"1": ["Cat1", "Cat2"], "2": ["Cat3"]}\n\n' +
			'Files:\n\n' + filesSection.join( '\n\n' );
	}

	function callLLM( prompt ) {
		return $.ajax( {
			url: CONFIG.llmProxyUrl,
			method: 'POST',
			contentType: 'application/json',
			data: JSON.stringify( {
				model: CONFIG.llmModel,
				messages: [ { role: 'user', content: prompt } ],
				max_tokens: CONFIG.llmMaxTokens,
				reasoning_effort: CONFIG.llmReasoningEffort,
				temperature: CONFIG.llmTemperature
			} ),
			dataType: 'json',
			timeout: 120000
		} ).then( function ( data ) {
			var choice = data.choices && data.choices[ 0 ];
			return {
				content: choice && choice.message.content || '',
				finishReason: choice && choice.finish_reason || ''
			};
		} );
	}

	// Returns { "File:Foo.jpg": [cats] } keyed by the real titles in
	// batchTitles, or null if the response contains no parseable JSON.
	function parseLLMResponse( responseText, validCatsSet, batchTitles ) {
		// Extract JSON from response (LLM may include markdown fences)
		var jsonMatch = responseText.match( /\{[\s\S]*\}/ );
		if ( !jsonMatch ) {
			return null;
		}

		var parsed;
		try {
			parsed = JSON.parse( jsonMatch[ 0 ] );
		} catch ( e ) {
			return null;
		}

		var result = {};
		var key, fileTitle, cats, validated, i, len, cat;

		for ( key in parsed ) {
			if ( !parsed.hasOwnProperty( key ) ) {
				continue;
			}
			cats = parsed[ key ];
			if ( !$.isArray( cats ) ) {
				continue;
			}

			// Keys are 1-based file numbers from the prompt. The model mangles
			// long filenames when echoing them, so we never key on names.
			fileTitle = batchTitles[ parseInt( key, 10 ) - 1 ];
			if ( !fileTitle ) {
				continue;
			}

			validated = [];
			for ( i = 0, len = cats.length; i < len; i++ ) {
				cat = String( cats[ i ] ).trim();
				if ( validCatsSet[ cat ] ) {
					validated.push( cat );
				}
			}
			result[ fileTitle ] = validated;
		}

		return result;
	}

	// -----------------------------------------------------------------------
	// Wake Lock: prevent browser from freezing the tab during analysis
	// -----------------------------------------------------------------------
	var wakeLockSentinel = null;
	var wakeLockActive = false;

	function acquireWakeLock() {
		wakeLockActive = true;
		requestWakeLock();
		// The Screen Wake Lock is released automatically when the tab becomes
		// hidden. Re-acquire it when the tab becomes visible again so the
		// analysis can keep running if the user switches away a second time.
		document.addEventListener( 'visibilitychange', onVisibilityChange );
	}

	function requestWakeLock() {
		if ( !wakeLockActive || !navigator.wakeLock ) {
			return;
		}
		navigator.wakeLock.request( 'screen' ).then( function ( sentinel ) {
			wakeLockSentinel = sentinel;
		}, function () {
			// Wake Lock denied (e.g. page not visible) – continue without it
		} );
	}

	function onVisibilityChange() {
		if ( document.visibilityState === 'visible' && wakeLockActive ) {
			requestWakeLock();
		}
	}

	function releaseWakeLock() {
		wakeLockActive = false;
		document.removeEventListener( 'visibilitychange', onVisibilityChange );
		if ( wakeLockSentinel ) {
			wakeLockSentinel.release();
			wakeLockSentinel = null;
		}
	}

	// -----------------------------------------------------------------------
	// Analysis pipeline (runs entirely in-browser)
	// -----------------------------------------------------------------------
	function startAnalysis() {
		if ( state.analysisStatus === 'running' ) {
			return;
		}

		// Clear previous results so a re-run starts fresh
		state.suggestions = {};
		state.subcategories = [];
		state.fileMetadata = {};
		state.failedBatches = 0;
		state.totalBatches = 0;
		state.analysisStatus = 'running';

		// Acquire a Web Lock to prevent the browser from freezing this tab
		// while the analysis is running in the background.
		acquireWakeLock();
		// Now that the analysis has been started explicitly by the user,
		// (re)inject per-thumbnail buttons so they appear only after the
		// script has been run at least once.
		injectThumbnailButtons();
		updateThumbnailButtons();

		// Step 1: Crawl subcategory tree
		updateStatus( 'Crawling subcategory tree…' );

		crawlSubcategoryTree().then( function ( subcatTitles ) {
			if ( subcatTitles.length === 0 ) {
				state.analysisStatus = 'done';
				state.suggestions = {};
				releaseWakeLock();
				updateStatus( 'No subcategories found.' );
				updatePanelProgress( 'No subcategories found.' );
				return;
			}

			// Strip "Category:" prefix for display and LLM prompt
			var subcatNames = [];
			var i, len;
			for ( i = 0, len = subcatTitles.length; i < len; i++ ) {
				subcatNames.push( subcatTitles[ i ].replace( /^Category:/, '' ) );
			}
			state.subcategories = subcatNames;

			updateStatus(
				'Found ' + subcatNames.length + ' subcategories. Fetching files…'
			);

			// Step 2: Fetch files
			return fetchCategoryFiles().then( function ( fileTitles ) {
				if ( fileTitles.length === 0 ) {
					state.analysisStatus = 'done';
					state.suggestions = {};
					saveCachedSuggestions();
					releaseWakeLock();
					updateStatus( 'No files found in category.' );
					updatePanelProgress( 'No files found in category.' );
					return;
				}

				updateStatus(
					'Fetching metadata for ' + fileTitles.length + ' files…'
				);

				// Step 3: Fetch file metadata
				return fetchFileDescriptions( fileTitles ).then( function ( metadata ) {
					state.fileMetadata = metadata;

					// Step 4: Batch LLM calls
					return runLLMBatches( subcatNames, metadata );
				} );
			} );
		} ).fail( function ( err ) {
			state.analysisStatus = 'error';
			releaseWakeLock();
			var errorMsg = 'Error: ' + ( err && err.message || err || 'Analysis failed.' );
			updateStatus( errorMsg );
			updatePanelProgress( errorMsg );
		} );
	}

	function runLLMBatches( subcatNames, metadata ) {
		var fileTitles = Object.keys( metadata );
		var totalBatches = Math.ceil( fileTitles.length / CONFIG.filesPerBatch );
		var batchIdx = 0;
		var allSuggestions = {};
		state.failedBatches = 0;
		state.totalBatches = totalBatches;

		// Build valid category set for validation
		var validCatsSet = {};
		var i, len;
		for ( i = 0, len = subcatNames.length; i < len; i++ ) {
			validCatsSet[ subcatNames[ i ] ] = true;
		}

		function processBatch() {
			if ( batchIdx >= totalBatches ) {
				// All batches done
				state.suggestions = allSuggestions;

				for ( i = 0, len = fileTitles.length; i < len; i++ ) {
					allSuggestions[ fileTitles[ i ] ] = addExistingSubcategories(
						allSuggestions[ fileTitles[ i ] ] || [],
						( metadata[ fileTitles[ i ] ] || {} ).categories || [],
						validCatsSet
					);
				}

				state.analysisStatus = 'done';
				saveCachedSuggestions();
				releaseWakeLock();
				updateThumbnailButtons();
				updatePanelProgress();
				return $.Deferred().resolve().promise();
			}

			var start = batchIdx * CONFIG.filesPerBatch;
			var end = Math.min( start + CONFIG.filesPerBatch, fileTitles.length );
			var batchTitles = fileTitles.slice( start, end );
			batchIdx++;

			updateStatus(
				'LLM batch ' + batchIdx + '/' + totalBatches +
				' (' + batchTitles.length + ' files)…'
			);

			// Build batch for prompt
			var fileBatch = [];
			var j, title, meta;
			for ( j = 0; j < batchTitles.length; j++ ) {
				title = batchTitles[ j ];
				meta = metadata[ title ] || {};
				fileBatch.push( {
					title: title,
					description: meta.description || '',
					categories: meta.categories || []
				} );
			}

			var prompt = buildLLMPrompt( subcatNames, fileBatch );

			return callLLM( prompt ).then( function ( response ) {
				var batchResult = parseLLMResponse(
					response.content, validCatsSet, batchTitles
				);
				if ( batchResult ) {
					$.extend( allSuggestions, batchResult );
				} else {
					state.failedBatches++;
					mw.log.warn(
						'CategoryDiffusion: LLM batch ' + batchIdx + ' returned no usable JSON' +
						' (finish_reason: ' + ( response.finishReason || 'unknown' ) + ').' +
						' Raw response:', response.content
					);
				}
				return processBatch();
			}, function ( err ) {
				state.failedBatches++;
				mw.log.warn( 'CategoryDiffusion: LLM batch ' + batchIdx + ' failed', err );
				// Continue with next batch
				return processBatch();
			} );
		}

		return processBatch();
	}

	// A file that is already in a subcategory of the category being diffused
	// only needs the parent removed. Offer those subcategories as suggestions
	// even if the LLM missed them, so the user can apply the removal with
	// one click. They render as "already present", which switches the
	// panel buttons to "Remove parent category".
	function addExistingSubcategories( suggestions, currentCats, validCatsSet ) {
		var result = suggestions.slice();
		var i, len, cat;
		for ( i = 0, len = currentCats.length; i < len; i++ ) {
			cat = currentCats[ i ];
			if ( validCatsSet[ cat ] && result.indexOf( cat ) === -1 ) {
				result.push( cat );
			}
		}
		return result;
	}

	// -----------------------------------------------------------------------
	// UI: Analyse button
	// -----------------------------------------------------------------------
	function createToolsLink() {
		var portletLink = mw.util.addPortletLink(
			'p-tb',
			'#',
			'Diffusor',
			't-catdiffusion',
			'Analyse this category with Diffusor'
		);
		if ( portletLink ) {
			$( portletLink ).on( 'click.catdiffusion', function ( e ) {
				e.preventDefault();
				openAnalysisPanel();
				startAnalysis();
			} );
		}
	}

	function updateStatus( text ) {
		updatePanelProgress( text );
	}

	function updatePanelProgress( currentStatus ) {
		var $status = $( '#catdiff-progress-status' );
		var $stages = $( '#catdiff-progress-stages' );
		
		if ( !currentStatus ) {
			currentStatus = '';
		}

		var stages = [];
		var currentStage = 'idle';

		if ( state.analysisStatus === 'running' ) {
			// Determine which stage we're in based on status text
			if ( currentStatus.indexOf( 'Crawling' ) >= 0 || currentStatus.indexOf( 'Depth' ) >= 0 ) {
				currentStage = 'crawling';
				stages.push( { name: 'Crawling subcategory tree', status: 'active', detail: currentStatus } );
				stages.push( { name: 'Fetching files', status: 'pending' } );
				stages.push( { name: 'Fetching file metadata', status: 'pending' } );
				stages.push( { name: 'Analyzing with LLM', status: 'pending' } );
			} else if ( currentStatus.indexOf( 'Fetching files' ) >= 0 || currentStatus.indexOf( 'Found' ) >= 0 && currentStatus.indexOf( 'subcategories' ) >= 0 ) {
				currentStage = 'fetching-files';
				stages.push( { name: 'Crawling subcategory tree', status: 'done' } );
				stages.push( { name: 'Fetching files', status: 'active', detail: currentStatus } );
				stages.push( { name: 'Fetching file metadata', status: 'pending' } );
				stages.push( { name: 'Analyzing with LLM', status: 'pending' } );
			} else if ( currentStatus.indexOf( 'Fetching metadata' ) >= 0 || currentStatus.indexOf( 'batch' ) >= 0 && currentStatus.indexOf( 'metadata' ) >= 0 ) {
				currentStage = 'fetching-metadata';
				stages.push( { name: 'Crawling subcategory tree', status: 'done' } );
				stages.push( { name: 'Fetching files', status: 'done' } );
				stages.push( { name: 'Fetching file metadata', status: 'active', detail: currentStatus } );
				stages.push( { name: 'Analyzing with LLM', status: 'pending' } );
			} else if ( currentStatus.indexOf( 'LLM' ) >= 0 || currentStatus.indexOf( 'batch' ) >= 0 ) {
				currentStage = 'llm';
				stages.push( { name: 'Crawling subcategory tree', status: 'done' } );
				stages.push( { name: 'Fetching files', status: 'done' } );
				stages.push( { name: 'Fetching file metadata', status: 'done' } );
				stages.push( { name: 'Analyzing with LLM', status: 'active', detail: currentStatus } );
			} else {
				// Fallback: show all stages with current status
				stages.push( { name: 'Crawling subcategory tree', status: 'pending' } );
				stages.push( { name: 'Fetching files', status: 'pending' } );
				stages.push( { name: 'Fetching file metadata', status: 'pending' } );
				stages.push( { name: 'Analyzing with LLM', status: 'pending' } );
			}
		} else if ( state.analysisStatus === 'done' ) {
			var fileCount = Object.keys( state.suggestions ).length;
			var withSuggestions = 0;
			var key;
			for ( key in state.suggestions ) {
				if ( state.suggestions.hasOwnProperty( key ) &&
					state.suggestions[ key ].length > 0 ) {
					withSuggestions++;
				}
			}
			
			stages.push( { name: 'Crawling subcategory tree', status: 'done' } );
			stages.push( { name: 'Fetching files', status: 'done' } );
			stages.push( { name: 'Fetching file metadata', status: 'done' } );
			stages.push( { name: 'Analyzing with LLM', status: 'done' } );
			
			if ( withSuggestions > 0 ) {
				$status.html(
					'<strong style="color: #14866d;">✓ Analysis complete!</strong><br>' +
					withSuggestions + ' of ' + fileCount + ' files have suggestions.<br>' +
					'Look for the green <b>View suggestions</b> buttons below each thumbnail.'
				);
			} else {
				$status.html(
					'<strong>Analysis complete.</strong><br>' +
					'No suggestions were generated for any file.'
				);
			}

			if ( state.failedBatches > 0 ) {
				$status.append(
					'<br><span style="color: #d33;">' + state.failedBatches + ' of ' +
					state.totalBatches + ' LLM batches failed; their files only have ' +
					'suggestions based on existing subcategories. See the browser ' +
					'console for details, or re-run the analysis.</span>'
				);
			}
		} else if ( state.analysisStatus === 'error' ) {
			$status.html( '<strong style="color: #d33;">Error:</strong> ' + ( currentStatus || 'Analysis failed.' ) );
			stages.push( { name: 'Crawling subcategory tree', status: 'error' } );
		} else {
			$status.text( currentStatus || 'Ready to start analysis.' );
		}

		// Render stages
		if ( stages.length > 0 ) {
			var html = '<ul style="list-style: none; padding: 0; margin: 12px 0;">';
			var i, len, stage, icon, color;
			for ( i = 0, len = stages.length; i < len; i++ ) {
				stage = stages[ i ];
				if ( stage.status === 'done' ) {
					icon = '✓';
					color = '#14866d';
				} else if ( stage.status === 'active' ) {
					icon = '⟳';
					color = '#36c';
				} else if ( stage.status === 'error' ) {
					icon = '✗';
					color = '#d33';
				} else {
					icon = '○';
					color = '#999';
				}
				html += '<li style="padding: 4px 0; color: ' + color + ';">';
				html += '<span style="font-weight: bold; margin-right: 6px;">' + icon + '</span>';
				html += stage.name;
				if ( stage.detail ) {
					html += ' <span style="font-size: 11px; color: #72777d;">(' + stage.detail + ')</span>';
				}
				html += '</li>';
			}
			html += '</ul>';
			$stages.html( html );
		} else {
			$stages.empty();
		}
	}

	// -----------------------------------------------------------------------
	// UI: Per-thumbnail suggest buttons
	// -----------------------------------------------------------------------
	function hasSuggestions( fileTitle ) {
		return !!( state.suggestions[ fileTitle ] &&
			state.suggestions[ fileTitle ].length );
	}

	// Once the user has added categories of their own, every analysed file
	// can be opened so those categories can be applied to it, not just the
	// files the LLM had suggestions for.
	function canOpenFile( fileTitle ) {
		if ( state.analysisStatus !== 'done' || !state.fileMetadata[ fileTitle ] ) {
			return false;
		}
		return hasSuggestions( fileTitle ) || state.customCategories.length > 0;
	}

	function injectThumbnailButtons() {
		// Hide per-thumbnail buttons until the script has actually been run
		// (or cached results are available). This avoids showing disabled
		// "View suggestions" buttons on first page load before analysis.
		if ( state.analysisStatus === 'idle' &&
			!Object.keys( state.suggestions ).length ) {
			return;
		}

		var $galleryItems = $( '.gallerybox' );
		var i, len, $item, $link, fileTitle, $btn;

		for ( i = 0, len = $galleryItems.length; i < len; i++ ) {
			$item = $galleryItems.eq( i );
			$link = $item.find( 'a.image, .thumb a' ).first();
			if ( !$link.length ) {
				continue;
			}

			fileTitle = extractFileTitleFromLink( $link );
			if ( !fileTitle ) {
				continue;
			}

			if ( $item.find( '.catdiff-suggest-btn' ).length ) {
				continue;
			}

			$btn = $( '<button>' )
				.addClass( 'catdiff-suggest-btn' )
				.attr( 'data-file', fileTitle )
				.text( 'View suggestions' )
				.prop( 'disabled', !canOpenFile( fileTitle ) );

			if ( state.reviewedFiles[ fileTitle ] ) {
				$btn.addClass( 'catdiff-reviewed' );
				$item.addClass( 'catdiff-gallery-reviewed' );
			}

			if ( hasSuggestions( fileTitle ) ) {
				$btn.addClass( 'catdiff-has-suggestions' );
			}

			$btn.on( 'click.catdiffusion', function ( e ) {
				e.preventDefault();
				e.stopPropagation();
				openPanel( $( this ).attr( 'data-file' ) );
			} );

			var $caption = $item.find( '.gallerytext' );
			if ( $caption.length ) {
				$caption.append( $btn );
			} else {
				$item.append( $btn );
			}
		}
	}

	function extractFileTitleFromLink( $link ) {
		var href = $link.attr( 'href' );
		if ( !href ) {
			return null;
		}
		var match = href.match( /\/wiki\/(File:[^?#]+)/ );
		if ( match ) {
			return decodeURIComponent( match[ 1 ].replace( /_/g, ' ' ) );
		}
		match = href.match( /title=(File:[^&#]+)/ );
		if ( match ) {
			return decodeURIComponent( match[ 1 ].replace( /_/g, ' ' ) );
		}
		return null;
	}

	function updateThumbnailButtons() {
		var $buttons = $( '.catdiff-suggest-btn' );
		var i, len, $btn, fileTitle;

		for ( i = 0, len = $buttons.length; i < len; i++ ) {
			$btn = $buttons.eq( i );
			fileTitle = $btn.attr( 'data-file' );

			$btn.prop( 'disabled', !canOpenFile( fileTitle ) );

			if ( state.reviewedFiles[ fileTitle ] ) {
				$btn.addClass( 'catdiff-reviewed' );
				$btn.closest( '.gallerybox' ).addClass( 'catdiff-gallery-reviewed' );
			}
			if ( hasSuggestions( fileTitle ) ) {
				$btn.addClass( 'catdiff-has-suggestions' );
			}
		}
	}

	// -----------------------------------------------------------------------
	// UI: Right-side panel
	// -----------------------------------------------------------------------
	function createPanel() {
		var html = [
			'<div id="catdiff-panel">',
			'  <button id="catdiff-panel-close" title="Close panel">&times;</button>',
			'  <h3 id="catdiff-panel-title">Diffusor</h3>',
			'  <div id="catdiff-panel-analysis-view">',
			'    <div class="catdiff-section">',
			'      <div class="catdiff-section-title">Analysis progress</div>',
			'      <div id="catdiff-progress-status">Ready to start analysis.</div>',
			'      <div id="catdiff-progress-stages"></div>',
			'    </div>',
			'  </div>',
			'  <div id="catdiff-panel-file-view" style="display: none;">',
			'    <img id="catdiff-panel-thumb" src="" alt="" />',
			'    <div class="catdiff-section">',
			'      <div class="catdiff-section-title">Description</div>',
			'      <div id="catdiff-description"></div>',
			'    </div>',
			'    <div class="catdiff-section">',
			'      <div class="catdiff-section-title">Current categories</div>',
			'      <ul id="catdiff-current-cats"></ul>',
			'    </div>',
			'    <div class="catdiff-section">',
			'      <div class="catdiff-section-title">Suggested categories</div>',
			'      <ul id="catdiff-suggestions-list"></ul>',
			'      <div id="catdiff-suggestion-count"></div>',
			'    </div>',
			'    <div class="catdiff-section">',
			'      <div class="catdiff-section-title">Your categories</div>',
			'      <ul id="catdiff-custom-list"></ul>',
			'      <form id="catdiff-custom-form">',
			'        <input id="catdiff-custom-input" type="text" placeholder="New or existing category" />',
			'        <button id="catdiff-custom-add" type="submit">Add</button>',
			'      </form>',
			'      <div id="catdiff-custom-status"></div>',
			'    </div>',
			'    <div class="catdiff-actions">',
			'      <button class="catdiff-btn-accept">Accept</button>',
			'      <button class="catdiff-btn-review" title="Opens the wikitext edit page in a new tab with the changes prefilled">Review in editor</button>',
			'      <button class="catdiff-btn-reject">Reject</button>',
			'    </div>',
			'  </div>',
			'</div>'
		].join( '\n' );

		$( 'body' ).append( html );

		$( '#catdiff-panel-close' ).on( 'click.catdiffusion', function ( e ) {
			e.preventDefault();
			closePanel();
		} );

		$( '.catdiff-btn-accept' ).on( 'click.catdiffusion', function ( e ) {
			e.preventDefault();
			acceptSuggestions();
		} );

		$( '.catdiff-btn-review' ).on( 'click.catdiffusion', function ( e ) {
			e.preventDefault();
			openSuggestionsInEditor();
		} );

		$( '.catdiff-btn-reject' ).on( 'click.catdiffusion', function ( e ) {
			e.preventDefault();
			rejectSuggestions();
		} );

		$( '#catdiff-panel' ).on( 'change.catdiffusion', 'input[data-cat]', updateActionLabels );

		$( '#catdiff-custom-form' ).on( 'submit.catdiffusion', function ( e ) {
			e.preventDefault();
			addCustomCategory();
		} );

		$( '#catdiff-custom-list' ).on( 'click.catdiffusion', '.catdiff-custom-remove', function ( e ) {
			e.preventDefault();
			removeCustomCategory( $( this ).attr( 'data-cat' ) );
		} );
	}

	function openAnalysisPanel() {
		var $panel = $( '#catdiff-panel' );
		$( '#catdiff-panel-title' ).text( 'Diffusor — ' + state.categoryTitle.replace( /^Category:/, '' ) );
		$( '#catdiff-panel-analysis-view' ).show();
		$( '#catdiff-panel-file-view' ).hide();
		$panel.addClass( 'catdiff-panel-open' );
		$( 'body' ).addClass( 'catdiff-panel-active' );
		updatePanelProgress();
	}

	function openPanel( fileTitle ) {
		state.currentFile = fileTitle;
		var $panel = $( '#catdiff-panel' );

		// Set title
		$( '#catdiff-panel-title' ).text( fileTitle.replace( /^File:/, '' ) );
		$( '#catdiff-panel-analysis-view' ).hide();
		$( '#catdiff-panel-file-view' ).show();
		$( '#catdiff-panel-thumb' ).attr( 'src', '' ).hide();
		$( '#catdiff-description' ).text( 'Loading…' );
		$( '#catdiff-current-cats' ).empty().append( '<li>Loading…</li>' );
		$( '#catdiff-suggestions-list' ).empty();
		$( '#catdiff-suggestion-count' ).text( '' );
		$( '#catdiff-custom-list' ).empty();
		setCustomStatus( '' );
		$( '.catdiff-btn-accept' ).prop( 'disabled', false );

		$panel.addClass( 'catdiff-panel-open' );
		$( 'body' ).addClass( 'catdiff-panel-active' );

		// Use cached metadata if available, otherwise fetch
		if ( state.fileMetadata[ fileTitle ] ) {
			populatePanelFromCache( fileTitle );
		}

		// Always fetch thumbnail (not cached in metadata)
		fetchThumbnail( fileTitle );
	}

	function closePanel() {
		state.currentFile = null;
		$( '#catdiff-panel' ).removeClass( 'catdiff-panel-open' );
		$( 'body' ).removeClass( 'catdiff-panel-active' );
	}

	function fetchThumbnail( fileTitle ) {
		var api = new mw.Api();
		api.get( {
			action: 'query',
			titles: fileTitle,
			prop: 'imageinfo',
			iiprop: 'url',
			iiurlwidth: 380,
			format: 'json'
		} ).then( function ( data ) {
			if ( state.currentFile !== fileTitle ) {
				return;
			}
			var pages = data.query.pages;
			var pageId = Object.keys( pages )[ 0 ];
			var page = pages[ pageId ];
			if ( page.imageinfo && page.imageinfo[ 0 ] ) {
				var url = page.imageinfo[ 0 ].thumburl || page.imageinfo[ 0 ].url;
				$( '#catdiff-panel-thumb' ).attr( 'src', url ).show();
			}
		} );
	}

	function populatePanelFromCache( fileTitle ) {
		var meta = state.fileMetadata[ fileTitle ] || {};

		// Description
		$( '#catdiff-description' ).text( meta.description || '(no description)' );

		// Current categories
		var currentCats = meta.categories || [];
		var $catList = $( '#catdiff-current-cats' ).empty();
		if ( currentCats.length === 0 ) {
			$catList.append( '<li>None</li>' );
		} else {
			var i, len;
			for ( i = 0, len = currentCats.length; i < len; i++ ) {
				$catList.append( $( '<li>' ).text( currentCats[ i ] ) );
			}
		}

		// Suggested categories
		var suggestions = state.suggestions[ fileTitle ] || [];
		renderSuggestions( suggestions, currentCats );
		renderCustomCategories( {} );
		updateActionLabels();
	}

	// -----------------------------------------------------------------------
	// UI: Suggestions rendering
	// -----------------------------------------------------------------------
	function renderSuggestions( suggestions, currentCats ) {
		var $list = $( '#catdiff-suggestions-list' ).empty();
		var $count = $( '#catdiff-suggestion-count' );

		if ( !suggestions || suggestions.length === 0 ) {
			$list.append( '<li>No suggestions available.</li>' );
			$count.text( '' );
			return;
		}

		var currentCatsSet = {};
		var i, len;
		for ( i = 0, len = currentCats.length; i < len; i++ ) {
			currentCatsSet[ currentCats[ i ] ] = true;
		}

		var newCount = 0;
		var alreadyCount = 0;

		for ( i = 0, len = suggestions.length; i < len; i++ ) {
			var catName = suggestions[ i ];
			var isPresent = !!currentCatsSet[ catName ];
			if ( isPresent ) {
				alreadyCount++;
			} else {
				newCount++;
			}
			$list.append( buildCategoryItem( catName, isPresent, !isPresent ) );
		}

		$count.text(
			suggestions.length + ' suggested, ' +
			alreadyCount + ' already present, ' +
			newCount + ' new'
		);
	}

	// A checkbox row for one category. Categories the file already has are
	// shown struck through and can't be selected.
	function buildCategoryItem( catName, isPresent, checked ) {
		var $li = $( '<li>' );
		var $label = $( '<label>' );
		var $checkbox = $( '<input>' )
			.attr( 'type', 'checkbox' )
			.attr( 'data-cat', catName );

		if ( isPresent ) {
			$checkbox.prop( 'disabled', true ).prop( 'checked', false );
			$label.addClass( 'catdiff-already-present' );
		} else {
			$checkbox.prop( 'checked', checked );
		}

		var catUrl = mw.util.getUrl( 'Category:' + catName );
		var $link = $( '<a>' )
			.attr( 'href', catUrl )
			.attr( 'target', '_blank' )
			.text( catName );
		$label.append( $checkbox, ' ', $link );
		$li.append( $label );
		return $li;
	}

	// Render the user's own categories for the current file. They start
	// unchecked (except those in checkedSet), since a category added for one
	// file usually fits only some of the others. Categories that are already
	// among this file's suggestions are shown there instead.
	function renderCustomCategories( checkedSet ) {
		var $list = $( '#catdiff-custom-list' ).empty();
		var meta = state.fileMetadata[ state.currentFile ] || {};
		var currentCats = meta.categories || [];
		var suggested = state.suggestions[ state.currentFile ] || [];
		var i, len, catName, $li;

		if ( !state.customCategories.length ) {
			$list.append(
				$( '<li>' )
					.addClass( 'catdiff-custom-hint' )
					.text( 'Categories you add here stay available for the other files in this category.' )
			);
			return;
		}

		for ( i = 0, len = state.customCategories.length; i < len; i++ ) {
			catName = state.customCategories[ i ];
			if ( suggested.indexOf( catName ) !== -1 ) {
				continue;
			}
			$li = buildCategoryItem(
				catName,
				currentCats.indexOf( catName ) !== -1,
				!!checkedSet[ catName ]
			);
			$li.append(
				' ',
				$( '<button>' )
					.addClass( 'catdiff-custom-remove' )
					.attr( 'type', 'button' )
					.attr( 'data-cat', catName )
					.attr( 'title', 'Remove from this list (does not delete the category)' )
					.html( '&times;' )
			);
			$list.append( $li );
		}
	}

	function getCheckedCustomSet() {
		var checked = {};
		$( '#catdiff-custom-list input[data-cat]:checked' ).each( function () {
			checked[ $( this ).attr( 'data-cat' ) ] = true;
		} );
		return checked;
	}

	// Update Accept and Review-in-editor button labels based on whether any
	// categories will be added. Both buttons relabel in lockstep so the
	// "remove parent only" path reads coherently across both actions.
	function updateActionLabels() {
		var hasNew = getSelectedCategories().length > 0;
		$( '.catdiff-btn-accept' ).text( hasNew ? 'Accept' : 'Remove parent category' );
		$( '.catdiff-btn-review' ).text( hasNew ? 'Review in editor' : 'Review removal in editor' );
	}

	function getSelectedCategories() {
		var selected = [];
		$( '#catdiff-panel-file-view input[data-cat]:checked:not(:disabled)' )
			.each( function () {
				var cat = $( this ).attr( 'data-cat' );
				if ( selected.indexOf( cat ) === -1 ) {
					selected.push( cat );
				}
			} );
		return selected;
	}

	// -----------------------------------------------------------------------
	// User-added categories
	// -----------------------------------------------------------------------
	function getParentCatName() {
		// wgPageName uses underscores, wikitext uses spaces
		return state.categoryTitle.replace( /^Category:/, '' ).replace( /_/g, ' ' );
	}

	function setCustomStatus( text, isError ) {
		$( '#catdiff-custom-status' )
			.text( text )
			.toggleClass( 'catdiff-error', !!isError );
	}

	// Resolves with true if the category had to be created, false if it
	// already existed. Rejects with an error message, or with nothing if the
	// user chose not to create it.
	function ensureCategoryExists( title ) {
		var api = new mw.Api();
		var prefixed = title.getPrefixedText();

		return api.get( {
			action: 'query',
			titles: prefixed,
			format: 'json'
		} ).then( function ( data ) {
			var pages = data.query.pages;
			var page = pages[ Object.keys( pages )[ 0 ] ];
			if ( !page.hasOwnProperty( 'missing' ) ) {
				return false;
			}

			var parentCat = getParentCatName();
			if ( !window.confirm(
				prefixed + ' does not exist yet.\n\n' +
				'Create it as a subcategory of Category:' + parentCat + '?'
			) ) {
				return $.Deferred().reject().promise();
			}

			return api.postWithEditToken( {
				action: 'edit',
				title: prefixed,
				text: '[[Category:' + parentCat + ']]',
				summary: 'Diffusor: created subcategory of [[Category:' + parentCat + ']]' +
					' ([[User:Alaexis/Diffusor.js|Diffusor]])',
				createonly: 1
			} ).then( function () {
				return true;
			}, function ( code, result ) {
				var detail = ( result && result.error && result.error.info ) || code;
				return $.Deferred().reject(
					'Failed to create ' + prefixed + ': ' + detail
				).promise();
			} );
		}, function () {
			return $.Deferred().reject(
				'Could not check whether ' + prefixed + ' exists.'
			).promise();
		} );
	}

	function addCustomCategory() {
		var $input = $( '#catdiff-custom-input' );
		var $add = $( '#catdiff-custom-add' );
		if ( $add.prop( 'disabled' ) ) {
			return;
		}

		var title = mw.Title.newFromText( $.trim( $input.val() ), 14 );
		if ( !title || title.getNamespaceId() !== 14 ) {
			setCustomStatus( 'Not a valid category name.', true );
			return;
		}
		var name = title.getMainText();
		var prefixed = title.getPrefixedText();
		if ( name === getParentCatName() ) {
			setCustomStatus( 'That is the category being diffused.', true );
			return;
		}

		var check = state.customCategories.indexOf( name ) !== -1 ?
			$.Deferred().resolve( false ).promise() :
			ensureCategoryExists( title );

		$add.prop( 'disabled', true );
		setCustomStatus( 'Checking ' + prefixed + '…' );

		check.then( function ( created ) {
			if ( state.customCategories.indexOf( name ) === -1 ) {
				state.customCategories.push( name );
				saveCustomCategories();
			}

			// Select it for the file being viewed
			var checked = getCheckedCustomSet();
			checked[ name ] = true;
			renderCustomCategories( checked );
			$( '#catdiff-suggestions-list input[data-cat="' +
				$.escapeSelector( name ) + '"]:not(:disabled)' ).prop( 'checked', true );
			updateActionLabels();
			updateThumbnailButtons();

			$input.val( '' );
			setCustomStatus( ( created ? 'Created ' : 'Added ' ) + prefixed + '.' );
		}, function ( msg ) {
			setCustomStatus( msg || '', !!msg );
		} ).always( function () {
			$add.prop( 'disabled', false );
		} );
	}

	function removeCustomCategory( name ) {
		var idx = state.customCategories.indexOf( name );
		if ( idx === -1 ) {
			return;
		}
		state.customCategories.splice( idx, 1 );
		saveCustomCategories();
		renderCustomCategories( getCheckedCustomSet() );
		updateActionLabels();
		updateThumbnailButtons();
	}

	// -----------------------------------------------------------------------
	// Actions: Accept / Reject
	// -----------------------------------------------------------------------
	// Fetch the current wikitext for state.currentFile and compute the new
	// wikitext + edit summary that reflects the selected suggestions. Shared
	// by acceptSuggestions() (API save) and openSuggestionsInEditor() (manual
	// review). Returns a Promise of { api, fileTitle, wikitext, summary }.
	function prepareEdit() {
		var fileTitle = state.currentFile;
		if ( !fileTitle ) {
			return $.Deferred().reject( 'no-current-file' ).promise();
		}

		var selectedCats = getSelectedCategories();
		var api = new mw.Api();

		return api.get( {
			action: 'query',
			titles: fileTitle,
			prop: 'revisions',
			rvprop: 'content',
			rvslots: 'main',
			format: 'json'
		} ).then( function ( data ) {
			var pages = data.query.pages;
			var pageId = Object.keys( pages )[ 0 ];
			var page = pages[ pageId ];
			var wikitext = '';

			if ( page.revisions && page.revisions[ 0 ] ) {
				var rev = page.revisions[ 0 ];
				if ( rev.slots && rev.slots.main ) {
					wikitext = rev.slots.main[ '*' ] || rev.slots.main.content || '';
				} else if ( rev[ '*' ] ) {
					wikitext = rev[ '*' ];
				}
			}

			// Remove the parent category being diffused and remember where it was
			var parentCat = getParentCatName();
			// Escape regex special characters
			var escapedCat = parentCat.replace( /[-.*+?^${}()|\\[\]\/]/g, '\\$&' );
			// Allow both underscores and spaces to match interchangeably
			escapedCat = escapedCat.replace( / /g, '[_ ]' );
			// Make first char case-insensitive (MediaWiki normalises this)
			var firstChar = escapedCat.charAt( 0 );
			if ( firstChar !== '[' ) {
				escapedCat = '[' + firstChar.toUpperCase() + firstChar.toLowerCase() + ']' +
					escapedCat.slice( 1 );
			}
			var catRegex = new RegExp(
				'\\n?\\s*\\[\\[\\s*[Cc]ategory\\s*:\\s*' + escapedCat +
				'(?:\\s*\\|[^\\]]*)?\\s*\\]\\]', 'g'
			);

			// Find all occurrences so we can both remove them and know where
			// in the wikitext to insert the new categories.
			var match;
			var firstMatchStart = null;
			var lastMatchEnd = null;

			while ( ( match = catRegex.exec( wikitext ) ) ) {
				if ( firstMatchStart === null ) {
					firstMatchStart = match.index;
				}
				lastMatchEnd = match.index + match[ 0 ].length;
			}

			if ( firstMatchStart === null ) {
				// Parent category not found – fall back to appending at the end
				var i, len;
				for ( i = 0, len = selectedCats.length; i < len; i++ ) {
					wikitext += '\n[[Category:' + selectedCats[ i ] + ']]';
				}
			} else {
				// Remove all occurrences of the parent category and insert the
				// new categories where the parent used to be.
				var before = wikitext.slice( 0, firstMatchStart );
				var after = wikitext.slice( lastMatchEnd );
				var insertion = '';
				var i, len;

				for ( i = 0, len = selectedCats.length; i < len; i++ ) {
					insertion += '\n[[Category:' + selectedCats[ i ] + ']]';
				}

				wikitext = before + insertion + after;
			}

			// Build a descriptive edit summary
			var summaryParts = [];
			if ( parentCat ) {
				summaryParts.push( 'removed [[Category:' + parentCat + ']]' );
			}
			if ( selectedCats.length ) {
				var addedCats = [];
				var i, len;
				for ( i = 0, len = selectedCats.length; i < len; i++ ) {
					addedCats.push( '[[Category:' + selectedCats[ i ] + ']]' );
				}
				summaryParts.push( 'added ' + addedCats.join( ', ' ) );
			}
			var humanSummary;
			if ( summaryParts.length ) {
				humanSummary = 'Diffusor: ' + summaryParts.join( '; ' );
			} else {
				humanSummary = 'Diffusor: removed parent category';
			}
			var fullSummary = humanSummary + ' ([[User:Alaexis/Diffusor.js|Diffusor]])';

			return {
				api: api,
				fileTitle: fileTitle,
				wikitext: wikitext,
				summary: fullSummary
			};
		} );
	}

	function acceptSuggestions() {
		var $accept = $( '.catdiff-btn-accept' );
		if ( $accept.prop( 'disabled' ) ) {
			return;
		}
		var startFile = state.currentFile;
		$accept.prop( 'disabled', true );
		function reenable() {
			if ( state.currentFile === startFile ) {
				$accept.prop( 'disabled', false );
			}
		}
		prepareEdit().then( function ( prep ) {
			prep.api.postWithEditToken( {
				action: 'edit',
				title: prep.fileTitle,
				text: prep.wikitext,
				summary: prep.summary
			} ).then( function () {
				markAsReviewed( prep.fileTitle );
				mw.notify( 'Saved categories on ' + prep.fileTitle, { type: 'success' } );
			}, function ( err ) {
				reenable();
				mw.log.warn( 'CategoryDiffusion: API edit failed', err );
				var detail = ( err && err.error && err.error.info ) || err || 'unknown error';
				mw.notify( 'Failed to save ' + prep.fileTitle + ': ' + detail, {
					type: 'error',
					autoHide: false
				} );
			} );
		}, reenable );
	}

	function openSuggestionsInEditor() {
		prepareEdit().then( function ( prep ) {
			// Stash the prepared wikitext for checkEditPagePrefill() to read
			// when the edit tab loads.
			var storageKey = CONFIG.localStoragePrefix + 'prefill-' +
				prep.fileTitle.replace( / /g, '_' );
			try {
				sessionStorage.setItem( storageKey, prep.wikitext );
			} catch ( e ) {
				// sessionStorage unavailable
			}

			markAsReviewed( prep.fileTitle );

			var editUrl = mw.util.getUrl( prep.fileTitle, {
				action: 'edit',
				summary: prep.summary
			} );
			window.open( editUrl, '_blank' );
		} );
	}

	function rejectSuggestions() {
		var fileTitle = state.currentFile;
		if ( !fileTitle ) {
			return;
		}
		markAsReviewed( fileTitle );
		
		// Move to the next unreviewed file with suggestions so users can
		// quickly step through items on the page without the panel closing.
		var $buttons = $( '.catdiff-suggest-btn' );
		var i, len, idx = -1;

		for ( i = 0, len = $buttons.length; i < len; i++ ) {
			if ( $buttons.eq( i ).attr( 'data-file' ) === fileTitle ) {
				idx = i;
				break;
			}
		}

		if ( idx === -1 ) {
			closePanel();
			return;
		}

		function openNextFrom( startIdx ) {
			var j, jLen, $btn, nextTitle;
			for ( j = startIdx, jLen = $buttons.length; j < jLen; j++ ) {
				$btn = $buttons.eq( j );
				nextTitle = $btn.attr( 'data-file' );
				if ( !nextTitle ) {
					continue;
				}
				if ( state.reviewedFiles[ nextTitle ] ) {
					continue;
				}
				if ( !canOpenFile( nextTitle ) ) {
					continue;
				}
				openPanel( nextTitle );
				return true;
			}
			return false;
		}

		// Try to move forward; if we reach the end, wrap around to the start.
		if ( !openNextFrom( idx + 1 ) && !openNextFrom( 0 ) ) {
			// No more suitable items – close the panel.
			closePanel();
		}
	}

	function markAsReviewed( fileTitle ) {
		state.reviewedFiles[ fileTitle ] = true;
		saveReviewedState();

		var $btn = $( '.catdiff-suggest-btn[data-file="' +
			$.escapeSelector( fileTitle ) + '"]' );
		$btn.addClass( 'catdiff-reviewed' );
		$btn.closest( '.gallerybox' ).addClass( 'catdiff-gallery-reviewed' );
	}

	// -----------------------------------------------------------------------
	// Edit page: prefill wikitext from sessionStorage
	// -----------------------------------------------------------------------
	function checkEditPagePrefill() {
		if ( mw.config.get( 'wgAction' ) !== 'edit' &&
			mw.config.get( 'wgAction' ) !== 'submit' ) {
			return;
		}

		var pageTitle = mw.config.get( 'wgPageName' ).replace( /_/g, ' ' );
		var storageKey = CONFIG.localStoragePrefix + 'prefill-' +
			pageTitle.replace( / /g, '_' );

		var prefillContent;
		try {
			prefillContent = sessionStorage.getItem( storageKey );
		} catch ( e ) {
			return;
		}
		if ( !prefillContent ) {
			return;
		}

		try {
			sessionStorage.removeItem( storageKey );
		} catch ( e ) {
			// ignore
		}

		$( function () {
			var $textarea = $( '#wpTextbox1' );
			if ( $textarea.length ) {
				$textarea.val( prefillContent );
				if ( $textarea[ 0 ] &&
					typeof $textarea[ 0 ].scrollTop !== 'undefined' ) {
					$textarea[ 0 ].scrollTop = $textarea[ 0 ].scrollHeight;
				}
			}
		} );
	}

	// -----------------------------------------------------------------------
	// Initialization
	// -----------------------------------------------------------------------
	function init() {
		injectStyles();
		loadReviewedState();
		loadCustomCategories();

		var hasCached = loadCachedSuggestions();

		createToolsLink();
		createPanel();
		injectThumbnailButtons();

		if ( hasCached ) {
			updateThumbnailButtons();
		}
	}

	// -----------------------------------------------------------------------
	// Entry point
	// -----------------------------------------------------------------------

	// Edit-page prefill runs on ALL pages (including edit tabs)
	checkEditPagePrefill();

	// Main UI only on category pages
	if ( mw.config.get( 'wgNamespaceNumber' ) !== 14 ) {
		return;
	}

	mw.loader.using(
		[ 'mediawiki.api', 'mediawiki.util', 'mediawiki.Title' ],
		init
	);

}() );