=== Structure Viewer ===
Contributors: blincks
Tags: ai assisted development, developer tools, file explorer, plugin inspector, ai context
Requires at least: 5.0
Tested up to: 6.9
Stable tag: 2.2.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Plugin URI: https://wordpress.org/plugins/structure-viewer
Author URI: https://www.blincks.com

Browse, inspect, and export any plugin or theme file structure — right from WordPress admin. For developers who build smarter with AI.

== Description ==

**The fastest way to feed your codebase to AI — and the easiest way to understand what you're feeding it.**

If you've ever copy-pasted a plugin folder into ChatGPT, Claude, Cursor, or Copilot, you already know the problem. AI tools are only as good as the context you give them. They can't fix what they can't see. And manually opening files, copying paths, and pasting them one by one — for every prompt, on every project — is the silent tax on AI-assisted development.

**Structure Viewer is the missing first step.** Browse any plugin or theme on your WordPress site, see its complete file tree at a glance, and export the entire structure as a single clean tree — TXT, JSON, XML, or one-click clipboard copy — that drops directly into any AI prompt as ready-to-use context. No FTP, no cPanel, no zipping folders, no guesswork.

Whether you're prompting an AI to refactor a plugin, audit third-party code, generate tests, write documentation, or trace a bug through someone else's theme — the conversation goes better when the AI knows the whole map up front.

= 🤖 Built for AI-Assisted Development =

Modern coding workflows look different than they did two years ago. You're working alongside an AI, and your AI works better when it has structural context. Structure Viewer is designed for exactly that workflow:

* **Tree-format exports** purpose-built for LLM context windows — clean ASCII, no markdown noise, token-efficient
* **One-click clipboard copy** — emoji tree format that pastes into any AI chat with perfect alignment
* **Filter before you export** — exclude `node_modules`, `vendor`, build artefacts, or anything you don't want bloating your context
* **Read source inline** — open any file in the browser modal, copy the snippet you need, paste into your AI conversation
* **Pro: Comparator** — diff two versions of a plugin and feed only the changed lines to your AI for targeted code review
* **Pro: FlatPack** — extract just the PHP, just the JS, or just the CSS from any plugin and hand the AI a focused codebase
* **WP-CLI exports** — script structure dumps directly into your AI agent's working directory

Stop pasting one file at a time. Give the AI the whole map first, then ask better questions.

---

= 🗂️ File Explorer =

See exactly what is inside every plugin and theme:

* **Interactive tree view** — expandable folders with icons for every file type (PHP, JS, CSS, images, JSON, XML, and more)
* **Searchable item picker** — switch between All Plugins, individual plugins, All Themes, and individual themes instantly
* **Live tree search** — type to filter files in real time, jump between matches with next/prev navigation
* **File type tag strip** — one click to show only PHP files, only CSS, only images — whatever you need
* **File size and modification dates** — see when each file was last changed, toggle on/off
* **Recently Viewed panel** — jump back to any file or folder you have already opened

= 📄 File Viewer =

Click any file to read it right there in your browser:

* Inline modal with **syntax highlighting** for all common languages
* **File metadata**: size, line count, last modified timestamp
* **Fullscreen mode** for reading long files without scrolling the page
* **One-click download** — get any file with the correct MIME type and original filename preserved

= 🔍 Search =

Find any file across your entire plugin or theme in seconds:

* **Real-time search** — results appear as you type, no page reloads
* **Extension search** — prefix with a dot to filter by type: `.php`, `.js`, `.css`, `.json`
* **File type dropdown** for quick narrowing
* Results show full relative path, file size, and last modified date

= 📤 Export =

Share or document your plugin structures in any format:

* **TXT** — clean ASCII tree, perfect for documentation, tickets, and AI context windows
* **JSON** — nested structure with file sizes and timestamps for programmatic use
* **XML** — standardized hierarchical format
* **PDF** — formatted document with header, page numbers, and automatic page breaks
* **Clipboard** — one-click emoji tree copy for pasting into Slack, Notion, or GitHub

= 📊 Dashboard =

Your WordPress file ecosystem at a glance:

* Stat tiles for total plugins, active/inactive split, total themes, and total files indexed
* **Largest plugins table** — instantly see which plugins are heaviest with file count and size bars
* WordPress environment strip: WP version, PHP version, active theme, site URL

= ⚙️ Settings =

Make it yours:

* **Dark mode / Light mode** — applied server-side, no flash on load
* **Accent color picker** — Emerald (default), Violet, Blue, Amber, or Rose
* Exclude hidden files, system directories, and custom patterns (`node_modules`, `.git`, `vendor`)
* Settings auto-save with instant confirmation toast

= 💻 WP-CLI =

Automate structure exports from the command line:

`wp structure-viewer export plugin <folder-name>`
`wp structure-viewer export theme <folder-name>`
`wp structure-viewer list plugins`
`wp structure-viewer list themes`

---

= 🚀 Structure Viewer Pro =

Unlock two powerful Pro tools for developers who need to go deeper.

**🔀 Comparator — Know Exactly What Changed**

Ever updated a plugin and wondered what actually changed? Comparator shows you a precise, color-coded, line-by-line diff between any two versions — so you can audit updates, review customizations, and catch unwanted changes before they cause problems.

* Compare two plugin ZIPs side by side
* Compare an installed plugin or theme against any uploaded ZIP
* Compare two individual files for a targeted spot-check
* Added lines in green, removed in red, changed lines clearly highlighted
* Works on large plugins and minified CSS/JS files — auto-tokenizes before diffing
* Expand/collapse per-file diff blocks to focus on what matters

**📦 FlatPack — Extract Only What You Need**

Need just the CSS from a plugin? Or all the PHP files for a code review? FlatPack extracts any plugin or theme ZIP and flattens it into a single, clean download — no nested folders, no hunting through directory trees.

* Upload any plugin or theme ZIP and see all its files in a live preview instantly
* Filter by PHP, CSS and JS, images, or any custom extension — preview updates live
* Only the filtered files are included in the output ZIP
* Smart collision-safe naming: duplicate basenames get a folder prefix automatically
* Download a single flat ZIP in seconds

**Upgrade to Pro from within the plugin — Settings → License → Upgrade to Pro.**

---

= 🔒 Security =

Security is not an afterthought. Every request to Structure Viewer is protected:

* **Nonce verification** on all AJAX endpoints
* **`manage_options` capability** required — administrators only, no public access
* **Path traversal prevention** — file paths resolved with `realpath()` and verified
* Input sanitized with `wp_unslash()` + `sanitize_text_field()` before use
* All output escaped before rendering
* Pro upload directories protected with `.htaccess` deny rules

= ⚡ Performance =

Structure Viewer is invisible to your site's frontend:

* Assets load **only on the Structure Viewer admin page** — zero impact on your site
* Dashboard stats cached with a **6-hour transient**
* **Lazy tree loading** — only trees you expand are scanned
* FlatPack preview filtering is entirely **client-side** — no extra AJAX round-trips
* No external HTTP requests at runtime

== Installation ==

1. Go to **Plugins → Add New** in your WordPress admin.
2. Search for **Structure Viewer**.
3. Click **Install Now**, then **Activate**.
4. Navigate to **Tools → Structure Viewer** to start exploring.

**Manual installation:**

1. Download the ZIP from WordPress.org.
2. Go to **Plugins → Add New → Upload Plugin**, upload the ZIP, click **Install Now**.
3. Activate and navigate to **Tools → Structure Viewer**.

TXT, JSON, XML, and clipboard export all work without any additional setup.

== Frequently Asked Questions ==

= What is Structure Viewer used for? =

Structure Viewer is a WordPress developer tool that lets you browse, search, view, and export the file structure of any installed plugin or theme — directly from your WordPress admin dashboard. It is used for code audits, plugin reviews, documentation, debugging, AI-assisted development, and general development workflows.

= How does Structure Viewer help with AI-assisted development? =

When you prompt an AI tool like ChatGPT, Claude, Cursor, or GitHub Copilot to work on a WordPress plugin or theme, the quality of its output depends almost entirely on the context you provide. Structure Viewer is built to make that first step painless.

Instead of opening files one at a time and copy-pasting code into a chat, you can: export the complete file tree of any plugin or theme as a single clean TXT, JSON, or XML payload; copy it to your clipboard with one click; paste it into your AI prompt as ready-to-use structural context. The AI now knows what files exist, how they're organised, and where to look — before you've even asked it a question. From there, you can drill into specific files in the browser modal and copy targeted snippets as needed.

For larger workflows, Structure Viewer Pro adds **Comparator** (so you can give the AI just the diff between two versions instead of two whole codebases) and **FlatPack** (so you can hand the AI only the PHP files, only the CSS, or any subset that matters for the task).

= Can I export a plugin's structure as AI prompt context? =

Yes — that is one of the main use cases. Use the Export tab to generate a TXT, JSON, or XML representation of any plugin or theme. The TXT format is intentionally token-efficient — clean ASCII tree, no markdown noise — so it fits cleanly inside an AI context window. You can also use the one-click clipboard copy to paste an emoji tree directly into ChatGPT, Claude, Cursor, or any other AI chat interface.

= Do I need FTP or server access to use it? =

No. Structure Viewer works entirely through the WordPress admin interface. You do not need FTP, cPanel, SSH, or any server-level access. If you are a WordPress administrator, you have everything you need.

= Who can access Structure Viewer? =

Only users with the `manage_options` capability — WordPress administrators by default. There is no frontend component and the plugin adds no public-facing pages or scripts.

= Can I view all my plugins at once? =

Yes. Select "All Plugins" from the item picker to see a collapsed tree for every installed plugin. Expand any plugin heading to drill into its files. The same applies to themes with "All Themes".

= Can I read the source code of a file? =

Yes. Click any text-based file in the tree to open it in the inline file viewer with syntax highlighting. Image files open in a new browser tab. The viewer also shows file size, line count, and last modified date.

= Can I download individual files? =

Yes. The file viewer has a one-click Download button. The file is served with the correct MIME type and its original filename.

= What export formats are available? =

TXT (plain ASCII tree), JSON (nested with metadata), XML, PDF, and Clipboard (emoji tree for pasting anywhere). You can choose your preferred clipboard format (JSON, Text, or XML) in Settings.

= Can I search inside a plugin's files? =

Yes. The Search tab lets you search by filename or extension across any plugin or theme in real time. Results show the full path, size, and last modified date.

= Can I exclude certain files or directories? =

Yes. Go to **Settings → Security and Exclusions** to toggle exclusions for hidden files and system directories, and to add your own custom patterns such as `vendor`, `node_modules`, `*.log`, or `.git`.

= Does it work with WP-CLI? =

Yes. You can export plugin and theme structures from the command line:

`wp structure-viewer export plugin <folder-name>`
`wp structure-viewer export theme <folder-name>`
`wp structure-viewer list plugins`
`wp structure-viewer list themes`

= Is there a Pro version? =

Yes. Structure Viewer Pro adds two features: **Comparator** (compare any two plugin or theme versions with a color-coded diff view) and **FlatPack** (extract and filter files from any plugin or theme ZIP by file type). The free version includes the full Explorer, Search, Export, Dashboard, and Settings. Upgrade from **Settings → Licence → Upgrade to Pro**.

= How does Comparator work? =

Upload two plugin ZIPs — or select an installed plugin and upload a ZIP to compare against it. Comparator produces a color-coded, file-by-file diff showing exactly which lines were added, removed, or changed. It handles large files and minified CSS/JS by tokenising them before diffing, so you get meaningful per-rule output instead of single-line change blocks.

= How does FlatPack work? =

Upload any plugin or theme ZIP. FlatPack extracts all its files and shows you a live-filterable preview. Select which file types you want — PHP, CSS and JS, images, or custom extensions — and click Run FlatPack. Only the matching files are packed into a single flat ZIP for download, no nested directories included.

= How does FlatPack handle files with the same name? =

Files with unique basenames keep their original name. When two or more files share the same basename (for example multiple `style.css` files from different directories), each is prefixed with its relative folder path — for example `assets-style.css` and `css-style.css`. Any remaining collisions get a numeric suffix.

= Does Structure Viewer affect site performance? =

No. Plugin assets are loaded only on the Structure Viewer admin page and have zero impact on your website's frontend. Dashboard stat counts are cached. No external requests are made at runtime.

= Does the plugin store any personal data? =

Structure Viewer stores settings in the `wp_options` table under `structureviewer_settings`. Temporary files uploaded for Comparator or FlatPack are stored in the WordPress uploads directory and deleted immediately after processing. No user data or personal information is collected or transmitted.

= Is Structure Viewer compatible with WordPress Multisite? =

The plugin is designed for single-site use. It may function on individual subsites within a Multisite network but Multisite-specific administration is not officially tested or supported.

== Changelog ==

= 2.2.0 =
* **New: Pro Comparator** — compare two plugin or theme versions with a color	-coded line-by-line diff; supports ZIPs, installed plugins/themes, and individual files; works with large and minified files
* **New: Pro FlatPack** — extract and filter files from any plugin or theme ZIP by type (PHP, CSS, JS, images, custom); download as a single flat ZIP with smart collision-safe naming
* **New: Dashboard redesign** — stat tiles with combined plugin and theme file count; async largest-plugins table; recently viewed panel; WordPress environment strip
* **New: Explorer improvements** — searchable item picker; live tree search with next/prev navigation; file type tag strip; lazy loading for all-items mode; AJAX refresh button (no page reload)
* **New: UI** — dark/light mode with server-side class; accent color picker with 5 options (default: Emerald); branded logo
* **New: Copy format setting** — choose JSON, Text, or XML as the clipboard copy format in Settings
* **New: Pro upsell placeholders** — free users see feature descriptions and a direct upgrade button in the Comparator and FlatPack tabs
* **Improved: Comparator diff engine** — patience algorithm for large files; correct deletion-before-addition ordering; minified file tokenization; similar-change pairing; raised limits (5 MB / 20,000 lines)
* **New: Accent color picker** — customize the plugin with the color you want to see.
* **Improved: FlatPack workflow** — extract-all-then-filter-live; reset on new file selection; filter pills built from actual ZIP contents
* **Improved: Settings** — auto-save with debounce and toast; exclusion patterns UI
* **Fixed: WordPress admin notices** — scoped text color to plugin container only; no longer overrides WP notice colors
* **Fixed: FlatPack** — protection files no longer appear in extracted file list
* **Fixed: Export / clipboard** — "undefined" output caused by buffer pollution resolved
* **Fixed: Bug Fixes** — Several bug fixes and security improvements

= 2.1.1 =
* Fixed: Copy Structure button not working in Safari.

= 2.1 =
* New: Download any individual file directly from the file viewer modal (all file types including binary)
* New: PDF export with styled header, monospace tree, page numbers, and automatic page breaks
* Security: download handler with path traversal prevention, nonce verification, and MIME type detection

= 2.0 =
* Complete UI/UX overhaul — modernized interface, modal file viewer with syntax highlighting
* Multi-format export: JSON and XML added alongside TXT
* Real-time search with file type filtering, one-click clipboard copy, keyboard navigation, WP-CLI

= 1.2 =
* Settings link added to plugin listing.

= 1.1 =
* Added TXT export.

= 1.0 =
* Initial release.

== Upgrade Notice ==

= 2.2.0 =
Major release: Redesigned dashboard, complete UI overhaul, and multiple bug fixes. Pro features added.

= 2.1.1 =
Fixes the Copy Structure button in Safari.

= 2.1 =
Adds individual file downloads and PDF export. Drop-in replacement.

= 2.0 =
Major update — full UI rebuild. Backward compatible.

== Screenshots ==

1. Dashboard — stat tiles, largest plugins table, recently viewed panel, and environment info
2. Dashboard appearance in Light Mode
3. Explorer tab — all installed plugins view
4. Explorer tab — interactive plugin file tree with live search and file type filtering
5. File viewer modal — source code with syntax highlighting, metadata, and download button
6. Multi-format export modal — TXT, JSON, XML, PDF, and clipboard options
7. Pro: Comparator — color-coded difference view between two plugin versions
8. Pro: FlatPack — live-filterable file preview