@runtimestudio/tailwind-sort-php 0.2.1 → 0.3.0

package/README.md

@@ -18,6 +18,15 @@ values, using a real PHP-aware lexer, and leaves everything else byte-identical.
 - **Zero-config** — reads `tailwindStylesheet` from your Prettier config, the same source of truth that
   `prettier-plugin-tailwindcss` uses.
 
+## Contents
+
+- [Requirements](#requirements) · [Install](#install) · [Setup](#setup) · [Usage](#usage)
+- [Editor integration](#editor-integration) — sort-on-save & pre-commit gate
+- [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations) — the per-file opt-in
+- [WordPress themes & plugins](#wordpress-themes--plugins)
+- [How it handles mixed templates](#how-it-handles-mixed-templates) · [Programmatic API](#programmatic-api) · [Known limitations](#known-limitations)
+- [Development](#development) · [License](#license)
+
 ## Requirements
 
 - **Node ≥ 22.18**, or **Bun** — both run the CLI and the programmatic API.
@@ -44,8 +53,8 @@ vocabulary. Any config format Prettier supports works (`.prettierrc`, `prettier.
 
 ```js
 export default {
-  plugins: ['prettier-plugin-tailwindcss'],
-  tailwindStylesheet: './resources/css/main.css',
+    plugins: ['prettier-plugin-tailwindcss'],
+    tailwindStylesheet: './resources/css/main.css',
 };
 ```
 
@@ -75,18 +84,22 @@ npx tailwind-sort-php init
 
 ### Options
 
-| Flag                  | Description                                                                                       |
-|-----------------------|---------------------------------------------------------------------------------------------------|
-| `--stylesheet <path>` | Tailwind v4 CSS entry. Defaults to `tailwindStylesheet` from your Prettier config.                |
-| `--attr <name>`       | Extra attribute to sort (repeatable). Merged with `tailwindAttributes` from your Prettier config. |
-| `--check`             | Don't write; exit 1 if any file needs sorting.                                                    |
-| `--no-short-tags`     | Don't treat bare `<?` as a PHP open tag.                                                          |
+| Flag                  | Description                                                                                                                                                                                    |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--stylesheet <path>` | Tailwind v4 CSS entry. Defaults to `tailwindStylesheet` from your Prettier config.                                                                                                             |
+| `--attr <name>`       | Extra attribute to sort (repeatable). Merged with `tailwindAttributes` from your Prettier config.                                                                                              |
+| `--php-source <glob>` | Also sort class strings in PHP declarations in matching files (repeatable). Merged with `tailwindPhpSources`. See [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations). |
+| `--check`             | Don't write; exit 1 if any file needs sorting.                                                                                                                                                 |
+| `--no-short-tags`     | Don't treat bare `<?` as a PHP open tag.                                                                                                                                                       |
 
 Default globs are all `.php` files under the cwd; `node_modules`, `vendor`, `dist`, and `.git` are always skipped.
 
 ## Editor integration
 
-No IDE plugin is needed — two small setups cover the common workflows.
+No IDE plugin is needed — two small setups cover the common workflows: sort-on-save and a pre-commit gate.
+
+<details>
+<summary><b>Sort on save</b> (PhpStorm / IntelliJ, VS Code) and a <b>pre-commit gate</b> — click to expand</summary>
 
 ### Sort on save (PhpStorm / IntelliJ)
 
@@ -107,14 +120,14 @@ to `.vscode/settings.json`:
 
 ```json
 {
-  "emeraldwalk.runonsave": {
-    "commands": [
-      {
-        "match": "\\.php$",
-        "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
-      }
-    ]
-  }
+    "emeraldwalk.runonsave": {
+        "commands": [
+            {
+                "match": "\\.php$",
+                "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
+            }
+        ]
+    }
 }
 ```
 
@@ -146,11 +159,103 @@ git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 ./node
 
 In CI there's no staged diff — just sweep the whole project with `npx tailwind-sort-php --check`.
 
+</details>
+
+## Sorting classes in PHP declarations
+
+By default, the tool only sorts classes inside HTML `class="..."` attributes. Class strings declared in **PHP itself** —
+constants, static properties, config arrays — sit inside PHP code the tool treats as opaque, so they're left alone.
+
+Opt in **per file** by listing the files whose PHP string values are Tailwind class lists, via `tailwindPhpSources` in
+your Prettier config (or the repeatable `--php-source <glob>` flag):
+
+```js
+export default {
+    plugins: ['prettier-plugin-tailwindcss'],
+    tailwindStylesheet: './resources/css/main.css',
+    tailwindPhpSources: ['src/classes/*.php'],
+};
+```
+
+With this set, every **string value** in a matched file is sorted with the exact same engine and order as the HTML
+side. In `key => value` arrays only the **value** is sorted — keys are never touched:
+
+```php
+// before
+public const array VARIANTS = array(
+    'primary'   => 'text-white px-4 bg-blue-600 rounded py-2',
+    'secondary' => 'text-gray-900 px-4 bg-gray-100 rounded py-2',
+);
+
+// after
+public const array VARIANTS = array(
+    'primary'   => 'rounded bg-blue-600 px-4 py-2 text-white',
+    'secondary' => 'rounded bg-gray-100 px-4 py-2 text-gray-900',
+);
+```
+
+Scalar declarations work the same way (`const string CARD = '...'`, `static $x = '...'`, `$x = '...'`), as do nested
+and list-style arrays.
+
+> **⚠️ Point `tailwindPhpSources` only at files whose string values are all Tailwind class lists.** The tool does
+> **not** guess whether a string "looks like" classes — within a matched file it sorts **every** eligible string value.
+> Aimed at a general file, it **will** reorder the words inside non-class strings (labels, URLs, SQL). This is a
+> deliberate design contract, not a bug: safety comes from your file-level opt-in, which is why a dedicated
+> directory of class-holder files (e.g. `src/classes/`) is the intended target.
+
+The opt-in is **inert at runtime** — it lives in formatter config only, never in your source. Your PHP stays vanilla,
+with zero coupling to this tool (no marker comments, no helper functions, no attributes).
+
+**Skipped automatically** (left byte-identical, even in a matched file):
+
+- Concatenated literals (`'btn-' . $variant`) — a fragment joined to dynamic code, unsafe to reorder.
+- Interpolated double-quoted strings (`"p-4 {$dynamic} flex"`).
+- Heredoc/nowdoc and backtick (shell-exec) strings, and strings containing escape sequences.
+
+**Off by default:** without `tailwindPhpSources` (and `--php-source`), behavior is identical to 0.2.x — no PHP
+declaration is ever touched.
+
+## WordPress themes & plugins
+
+Most WordPress sorting needs **no opt-in at all**. Template files and partials output markup, and the `class="..."`
+in that markup is sorted by the default HTML pass — even when the value is interrupted by PHP:
+
+```php
+<article <?php post_class( 'z-10 flex' ); ?>>
+  <h2 class="text-2xl font-bold <?= $featured ? 'text-amber-600' : '' ?> tracking-tight">
+```
+
+`tailwindPhpSources` is only for classes you store in **PHP values** — a variant map, a config array, theme defaults.
+For that, **don't opt in a general partial.** Partials are full of non-class strings — `__()` translations,
+`get_template_part()` names, query args, URLs — and an opted-in file sorts _every_ multi-word string value. The Tailwind
+sorter leaves most prose alone (unknown words keep their order), but it **will** reorder any string containing words
+that are also utilities (`grid`, `block`, `flex`, `hidden`, `container`, `table`, …), so `'Switch to grid view'`
+becomes `'Switch to view grid'`.
+
+Instead, keep class maps in a **dedicated file** whose every value is a class list, and opt in only that file:
+
+```php
+// inc/ui-classes.php   →   tailwindPhpSources: ['inc/ui-classes.php']
+return array(
+    'button' => array(
+        'primary'   => 'rounded bg-blue-600 px-4 py-2 text-white',
+        'secondary' => 'rounded bg-gray-100 px-4 py-2 text-gray-900',
+    ),
+    'card'   => 'rounded-lg border bg-white p-6 shadow-sm',
+);
+```
+
+`require` that map from your partials. The map file is 100% class strings (safe to sort); the partials stay out of
+`tailwindPhpSources` and get their markup sorted by the HTML pass as usual.
+
 ## How it handles mixed templates
 
 PHP islands inside a class attribute are treated as opaque atoms that never move. Static text between islands is sorted
 independently — the same model the official plugin uses for `${}` interpolations in template literals.
 
+<details>
+<summary>Glued-fragment pinning, whitespace handling, and the full edge-case list — click to expand</summary>
+
 ```php
 <!-- before -->
 <h2 class="text-2xl font-bold <?= $featured ? 'text-amber-600' : '' ?> tracking-tight leading-snug">
@@ -173,8 +278,10 @@ Also handled correctly:
 - `?>` inside `//` and `#` line comments (island ends — genuine PHP behavior)
 - `#[Attributes]`, `<?PHP` case-insensitivity, `<?xml` exclusion, files ending in PHP mode
 - PHP islands as standalone attributes: `<div <?php post_class(); ?> class="...">`
-- `<script>`/`<style>` content, HTML comments, and `echo '<div class="...">'` strings are left alone (sorting
-  `class="..."` inside PHP string literals could be added later as an opt-in)
+- `<script>`/`<style>` content, HTML comments, and `echo '<div class="...">'` strings are left alone (to sort class
+  strings declared in PHP, see [Sorting classes in PHP declarations](#sorting-classes-in-php-declarations))
+
+</details>
 
 ## Programmatic API
 
@@ -190,6 +297,9 @@ const out = transform(source, sortFn);
 
 ## Known limitations
 
+<details>
+<summary>Edge cases and unsupported syntax — click to expand</summary>
+
 - Complex string interpolation containing double quotes (`"{$arr["key"]}"`) can desync the PHP string lexer in rare
   cases. Use `{$arr['key']}` style or extract to a variable.
 - Unquoted attribute values (`class=foo`) are skipped.
@@ -197,6 +307,8 @@ const out = transform(source, sortFn);
   classes).
 - Whitespace inside multi-line class attributes is normalized to single spaces (matches Prettier behavior).
 
+</details>
+
 ## Development
 
 ```sh
@@ -204,10 +316,10 @@ bun test      # or: node --test "test/*.test.ts"
 bun run build # compile src → dist (tsc); the published artifact
 ```
 
-54 tests: 41 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`), 5
-integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the Tailwind
-toolchain isn't installed, and 8 `init` tests that run against throwaway git repositories and skip when `git` is
-unavailable.
+74 tests: 59 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`),
+7 integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the
+Tailwind toolchain isn't installed, and 8 `init` tests that run against throwaway git repositories and skip when
+`git` is unavailable.
 
 ## License
 

package/dist/cli.d.ts

@@ -9,6 +9,7 @@
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
  *   --attr <name> Extra attribute to sort (repeatable)
+ *   --php-source <glob> Also sort class strings in PHP declarations in matching files (repeatable)
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *

package/dist/cli.js

@@ -9,6 +9,7 @@
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
  *   --attr <name> Extra attribute to sort (repeatable)
+ *   --php-source <glob> Also sort class strings in PHP declarations in matching files (repeatable)
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *
@@ -30,6 +31,7 @@ function parseArgs(argv) {
     const cli = {
         globs: [],
         attrs: ['class', 'className'],
+        phpSources: [],
         check: false,
         shortTags: true,
     };
@@ -43,6 +45,8 @@ function parseArgs(argv) {
             cli.stylesheet = argv[++i];
         else if (a === '--attr')
             cli.attrs.push(argv[++i]);
+        else if (a === '--php-source')
+            cli.phpSources.push(argv[++i]);
         else if (a.startsWith('--')) {
             console.error(`Unknown option: ${a}`);
             process.exit(2);
@@ -83,11 +87,10 @@ async function* scanFiles(globs) {
  */
 const ignored = (file) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
 /**
- * Best-effort read of the project's resolved Prettier config, so this tool shares one source of truth with
- * `prettier-plugin-tailwindcss`. Picks up `tailwindStylesheet` (resolved relative to the config file) and
- * `tailwindAttributes` (merged into the attribute list).
+ * Best-effort read of the resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
+ * Picks up `tailwindStylesheet`, `tailwindAttributes`, and `tailwindPhpSources`.
  *
- * @returns The resolved stylesheet path and attributes, or an empty object if none are available.
+ * @returns The found settings, or an empty object if none are available.
  */
 async function fromPrettierConfig() {
     try {
@@ -106,6 +109,9 @@ async function fromPrettierConfig() {
         if (Array.isArray(cfg.tailwindAttributes)) {
             out.attributes = cfg.tailwindAttributes.filter((a) => typeof a === 'string' && !a.startsWith('/'));
         }
+        if (Array.isArray(cfg.tailwindPhpSources)) {
+            out.phpSources = cfg.tailwindPhpSources.filter((p) => typeof p === 'string');
+        }
         return out;
     }
     catch {
@@ -135,24 +141,32 @@ async function main() {
         attributes: cli.attrs,
         shortOpenTags: cli.shortTags,
     };
+    // Pre-scan the opt-in `tailwindPhpSources` globs; a file gets `sortPhpStrings` only if it matches one.
+    const phpSources = [...cli.phpSources, ...(pc.phpSources ?? [])];
+    const phpSourceFiles = new Set();
+    for await (const file of scanFiles(phpSources)) {
+        if (!ignored(file))
+            phpSourceFiles.add(file);
+    }
     let scanned = 0;
     let changed = 0;
-    for (const pattern of cli.globs) {
-        for await (const file of scanFiles([pattern])) {
-            if (ignored(file))
-                continue;
-            scanned++;
-            const src = await readFile(file, 'utf8');
-            const out = transform(src, sortFn, opts);
-            if (out !== src) {
-                changed++;
-                if (cli.check) {
-                    console.log(`needs sorting: ${file}`);
-                }
-                else {
-                    await writeFile(file, out);
-                    console.log(`sorted: ${file}`);
-                }
+    const seen = new Set();
+    // Include php-source files so a designated holder is sorted even outside the main globs; `seen` dedupes.
+    for await (const file of scanFiles([...cli.globs, ...phpSources])) {
+        if (ignored(file) || seen.has(file))
+            continue;
+        seen.add(file);
+        scanned++;
+        const src = await readFile(file, 'utf8');
+        const out = transform(src, sortFn, { ...opts, sortPhpStrings: phpSourceFiles.has(file) });
+        if (out !== src) {
+            changed++;
+            if (cli.check) {
+                console.log(`needs sorting: ${file}`);
+            }
+            else {
+                await writeFile(file, out);
+                console.log(`sorted: ${file}`);
             }
         }
     }

package/dist/index.d.ts

@@ -10,4 +10,5 @@
 export { transform, type SortFn, type TransformOptions } from './transform.ts';
 export { findIslands, type Island, type IslandOptions } from './islands.ts';
 export { maskIslands, findClassAttributes, type ClassAttr, type HtmlScanOptions } from './html.ts';
+export { findSortablePhpStrings, type PhpStringRange } from './php-strings.ts';
 export { createTailwindSortFn, type SorterOptions } from './sorter.ts';

package/dist/index.js

@@ -10,4 +10,5 @@
 export { transform } from "./transform.js";
 export { findIslands } from "./islands.js";
 export { maskIslands, findClassAttributes } from "./html.js";
+export { findSortablePhpStrings } from "./php-strings.js";
 export { createTailwindSortFn } from "./sorter.js";

package/dist/init.js

@@ -132,7 +132,11 @@ export async function runInit(argv) {
     let repairMode = false;
     if (current !== null && current !== hookBody) {
         if (!cli.force) {
-            const installed = current === HOOK_CHECK ? 'the check variant' : current === HOOK_FIX ? 'the --fix variant' : 'a custom hook';
+            const installed = current === HOOK_CHECK
+                ? 'the check variant'
+                : current === HOOK_FIX
+                    ? 'the --fix variant'
+                    : 'a custom hook';
             fail(`${HOOK_PATH} already exists and differs (${installed} is installed). Re-run with --force to overwrite.`);
         }
         writeHook = true;
@@ -148,7 +152,9 @@ export async function runInit(argv) {
             await writeFile(hookAbs, hookBody);
             await chmod(hookAbs, 0o755);
         }
-        done.push(cli.dryRun ? `would install ${HOOK_PATH} (${variant} variant)` : `installed ${HOOK_PATH} (${variant} variant)`);
+        done.push(cli.dryRun
+            ? `would install ${HOOK_PATH} (${variant} variant)`
+            : `installed ${HOOK_PATH} (${variant} variant)`);
     }
     if (repairMode) {
         if (!cli.dryRun)

package/dist/php-strings.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+import type { Island } from './islands.ts';
+/**
+ * Inner byte range of a sortable string literal — the span *between* the quotes, in original-source offsets.
+ */
+export interface PhpStringRange {
+    /**
+     * Offset of the first character inside the quotes.
+     */
+    start: number;
+    /**
+     * Offset just past the last character inside the quotes (exclusive).
+     */
+    end: number;
+}
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export declare function findSortablePhpStrings(src: string, islands: Island[]): PhpStringRange[];

package/dist/php-strings.js

@@ -0,0 +1,230 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+const isIdentStart = (c) => /[A-Za-z_€-￿]/.test(c);
+const isIdent = (c) => /[A-Za-z0-9_€-￿]/.test(c);
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export function findSortablePhpStrings(src, islands) {
+    const ranges = [];
+    for (const isl of islands) {
+        const tokens = tokenizeIsland(src, isl.start, isl.end);
+        for (let k = 0; k < tokens.length; k++) {
+            const token = tokens[k];
+            if (token.kind !== 'string' || token.skip)
+                continue;
+            const next = tokens[k + 1];
+            const prev = tokens[k - 1];
+            // Array key (`'left' => ...`) — never sorted.
+            if (next && next.kind === 'arrow')
+                continue;
+            // Part of a concatenation expression (`'btn-' . $v` / `$v . 'suffix'`).
+            if ((next && next.kind === 'dot') || (prev && prev.kind === 'dot'))
+                continue;
+            ranges.push({ start: token.start, end: token.end });
+        }
+    }
+    return ranges;
+}
+/**
+ * Tokenize one PHP island into the minimal token stream needed for value classification: string literals
+ * (with their inner range and a skip flag), the `=>` arrow, the `.` concatenation operator, and a coalesced `other`
+ * marker for everything else. Whitespace and comments are dropped so adjacency is judged across them.
+ */
+function tokenizeIsland(src, start, end) {
+    const tokens = [];
+    const pushOther = () => {
+        if (tokens.length === 0 || tokens[tokens.length - 1].kind !== 'other')
+            tokens.push({ kind: 'other' });
+    };
+    let i = start;
+    while (i < end) {
+        const c = src[i];
+        // Whitespace.
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === '\v') {
+            i++;
+            continue;
+        }
+        // Line comments (`//`, `#`) — but `#[` opens a PHP 8 attribute, which is code.
+        if (c === '/' && src[i + 1] === '/') {
+            i = skipLineComment(src, i + 2, end);
+            continue;
+        }
+        if (c === '#' && src[i + 1] !== '[') {
+            i = skipLineComment(src, i + 1, end);
+            continue;
+        }
+        // Block comment.
+        if (c === '/' && src[i + 1] === '*') {
+            const close = src.indexOf('*/', i + 2);
+            i = close === -1 || close + 2 > end ? end : close + 2;
+            continue;
+        }
+        // Heredoc / nowdoc — never harvested; skip the whole construct.
+        if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
+            const here = skipHeredoc(src, i + 3, end);
+            if (here !== -1) {
+                i = here;
+                pushOther();
+                continue;
+            }
+        }
+        // Quoted strings.
+        if (c === "'") {
+            const close = scanQuoted(src, i + 1, "'", end);
+            const inner = src.slice(i + 1, close);
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: inner.includes('\\') });
+            i = close + 1;
+            continue;
+        }
+        if (c === '"') {
+            const close = scanQuoted(src, i + 1, '"', end);
+            const inner = src.slice(i + 1, close);
+            // Skip interpolation (any unescaped `$`) and escapes.
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: hasInterpolationOrEscape(inner) });
+            i = close + 1;
+            continue;
+        }
+        if (c === '`') {
+            // Shell-exec string — never a class list.
+            i = scanQuoted(src, i + 1, '`', end) + 1;
+            pushOther();
+            continue;
+        }
+        // Operators that matter for classification.
+        if (c === '=' && src[i + 1] === '>') {
+            tokens.push({ kind: 'arrow' });
+            i += 2;
+            continue;
+        }
+        if (c === '.') {
+            tokens.push({ kind: 'dot' });
+            i++;
+            continue;
+        }
+        // Everything else (identifiers, punctuation, the `<?php`/`?>` tags themselves).
+        pushOther();
+        if (isIdentStart(c)) {
+            i++;
+            while (i < end && isIdent(src[i]))
+                i++;
+        }
+        else {
+            i++;
+        }
+    }
+    return tokens;
+}
+/**
+ * Scan a quoted string body; `i` is just past the open quote. Returns the offset of the closing quote (or `end`).
+ */
+function scanQuoted(src, i, quote, end) {
+    while (i < end) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === quote)
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Skip a `//`/`#` line comment body, ending at a newline or `?>`. Returns the offset to resume scanning from.
+ */
+function skipLineComment(src, i, end) {
+    while (i < end) {
+        if (src[i] === '\n')
+            return i + 1;
+        if (src[i] === '?' && src[i + 1] === '>')
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * True if a double-quoted body contains interpolation (an unescaped `$`) or any escape sequence.
+ */
+function hasInterpolationOrEscape(body) {
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '\\')
+            return true;
+        if (c === '$')
+            return true;
+    }
+    return false;
+}
+/**
+ * Skip a heredoc/nowdoc; `i` is just past `<<<`. Returns the offset past the closing identifier line,
+ * or -1 if `<<<` isn't followed by a valid heredoc identifier. Mirrors the boundary rules of the island lexer.
+ */
+function skipHeredoc(src, i, end) {
+    while (i < end && (src[i] === ' ' || src[i] === '\t'))
+        i++;
+    let quote = '';
+    if (src[i] === "'" || src[i] === '"') {
+        quote = src[i];
+        i++;
+    }
+    if (i >= end || !isIdentStart(src[i]))
+        return -1;
+    const idStart = i;
+    while (i < end && isIdent(src[i]))
+        i++;
+    const id = src.slice(idStart, i);
+    if (quote) {
+        if (src[i] !== quote)
+            return -1;
+        i++;
+    }
+    while (i < end && src[i] === '\r')
+        i++;
+    if (src[i] !== '\n')
+        return -1;
+    i++;
+    while (i < end) {
+        let j = i;
+        while (j < end && (src[j] === ' ' || src[j] === '\t'))
+            j++;
+        if (src.startsWith(id, j)) {
+            const k = j + id.length;
+            if (k >= end || !isIdent(src[k]))
+                return k;
+        }
+        const nl = src.indexOf('\n', i);
+        if (nl === -1 || nl >= end)
+            return end;
+        i = nl + 1;
+    }
+    return end;
+}