com.wallstop-studios.unity-helpers 2.0.0-rc81.6 → 2.0.0-rc81.9

package/.github/workflows/csharpier.yml

@@ -0,0 +1,135 @@
+name: CSharpier
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  format-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Restore dotnet tools
+        run: dotnet tool restore
+
+      - name: CSharpier check
+        id: csharpier_check
+        run: |
+          dotnet tool run csharpier check .
+        continue-on-error: true
+
+      - name: Generate CSharpier diff
+        if: ${{ steps.csharpier_check.outcome == 'failure' }}
+        run: |
+          echo "Formatting issues detected. Generating diff..."
+          dotnet tool run csharpier format .
+          git config user.email "actions@github.com"
+          git config user.name "github-actions[bot]"
+          git diff > csharpier.patch || true
+          # Provide a concise summary, too
+          git status --porcelain > csharpier_changed_files.txt
+
+      - name: Skip PR comment on fork
+        if: ${{ github.event_name == 'pull_request' && steps.csharpier_check.outcome == 'failure' && github.event.pull_request.head.repo.fork }}
+        run: |
+          echo "Forked PR detected; skipping sticky PR comment due to restricted permissions. Full diff uploaded as artifact."
+          {
+            echo "## CSharpier Formatting Issues Detected"
+            echo ""
+            echo "- PR is from a fork; comment skipped due to token restrictions."
+            echo "- Full diff uploaded as artifact 'csharpier-diff'."
+          } >> $GITHUB_STEP_SUMMARY
+
+      - name: Read diff for comment
+        if: ${{ github.event_name == 'pull_request' && steps.csharpier_check.outcome == 'failure' && !github.event.pull_request.head.repo.fork }}
+        id: read_diff
+        shell: bash
+        run: |
+          # Limit diff size in comment to ~60KB to avoid API limits
+          max=60000
+          content=$(cat csharpier.patch)
+          if [ ${#content} -gt $max ]; then
+            echo "diff<<EOF" >> $GITHUB_OUTPUT
+            echo "(Diff too large for inline comment. See attached artifact 'csharpier-diff'.)" >> $GITHUB_OUTPUT
+            echo EOF >> $GITHUB_OUTPUT
+          else
+            echo "diff<<EOF" >> $GITHUB_OUTPUT
+            printf '%s\n' "$content" >> $GITHUB_OUTPUT
+            echo EOF >> $GITHUB_OUTPUT
+          fi
+
+      - name: Post CSharpier suggestion comment
+        if: ${{ github.event_name == 'pull_request' && steps.csharpier_check.outcome == 'failure' && !github.event.pull_request.head.repo.fork }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: csharpier-formatting
+          message: |
+            CSharpier found formatting changes. This job is failing until formatting is applied.
+
+            To apply locally:
+            1) dotnet tool restore
+            2) dotnet tool run csharpier format .
+
+            Diff of proposed changes:
+
+            ```diff
+            ${{ steps.read_diff.outputs.diff }}
+            ```
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Attach full patch as artifact
+        if: ${{ steps.csharpier_check.outcome == 'failure' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: csharpier-diff
+          path: |
+            csharpier.patch
+            csharpier_changed_files.txt
+
+      - name: Job summary (formatting required)
+        if: ${{ steps.csharpier_check.outcome == 'failure' }}
+        run: |
+          {
+            echo "## CSharpier Formatting Required"
+            echo ""
+            echo "- The formatter detected changes that need to be applied."
+            echo "- Apply locally: dotnet tool restore && dotnet tool run csharpier format ."
+            echo "- Changed files and full patch are uploaded as 'csharpier-diff' artifact."
+          } >> $GITHUB_STEP_SUMMARY
+          if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ github.event.pull_request.head.repo.fork }}" = "true" ]; then
+            echo "- PR comment was skipped because this is a fork." >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Fail if formatting required
+        if: ${{ steps.csharpier_check.outcome == 'failure' }}
+        run: |
+          echo "CSharpier formatting required. Failing the job." 1>&2
+          exit 1
+
+      - name: Success summary
+        if: ${{ steps.csharpier_check.outcome == 'success' }}
+        run: |
+          echo "CSharpier check passed."
+          {
+            echo "## CSharpier Check Passed"
+            echo ""
+            echo "- No formatting changes required."
+          } >> $GITHUB_STEP_SUMMARY
+
+      

package/.github/workflows/lint-doc-links.yml

@@ -0,0 +1,27 @@
+name: Lint Docs Links
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run Markdown link linter
+        shell: pwsh
+        run: ./scripts/lint-doc-links.ps1 -VerboseOutput
+
+      - name: Check dead links (lychee)
+        uses: lycheeverse/lychee-action@v1
+        with:
+          args: >
+            --config .lychee.toml
+            **/*.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/markdown-json.yml

@@ -0,0 +1,41 @@
+name: Markdown & JSON Lint/Format
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: package.json
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm i --no-audit --no-fund
+          fi
+
+      - name: Prettier check (Markdown)
+        run: npm run format:md:check
+
+      - name: Prettier check (JSON / asmdef / asmref)
+        run: npm run format:json:check
+
+      - name: Markdown lint
+        run: npm run lint:markdown

package/.github/workflows/npm-publish.yml

@@ -1,75 +1,75 @@
-name: Publish to NPM
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'package.json'
-  workflow_dispatch:
-
-jobs:
-  publish_npm:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0  # Ensure full commit history for version comparison
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v5
-        with:
-          node-version: 18
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Check if version changed
-        id: version_check
-        run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "Manual trigger detected. Skipping version check."
-            NEW_VERSION=$(jq -r '.version' package.json)
-            echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
-            echo "should_publish=true" >> $GITHUB_ENV
-            if [[ "$NEW_VERSION" == *"rc"* ]]; then
-              echo "This is a pre-release (next tag)."
-              echo "NPM_TAG=next" >> $GITHUB_ENV
-            else
-              echo "This is a stable release (latest tag)."
-              echo "NPM_TAG=latest" >> $GITHUB_ENV
-            fi
-          else
-            PREV_VERSION=$(git show HEAD~1:package.json | jq -r '.version' || echo "0.0.0")
-            NEW_VERSION=$(jq -r '.version' package.json)
-            echo "Previous version: $PREV_VERSION"
-            echo "New version: $NEW_VERSION"
-
-            if [ "$PREV_VERSION" != "$NEW_VERSION" ]; then
-              echo "Version changed, proceeding..."
-              echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
-              echo "should_publish=true" >> $GITHUB_ENV
-
-              # Detect pre-releases (versions with "rc" or similar tags)
-              if [[ "$NEW_VERSION" == *"rc"* ]]; then
-                echo "This is a pre-release (next tag)."
-                echo "NPM_TAG=next" >> $GITHUB_ENV
-              else
-                echo "This is a stable release (latest tag)."
-                echo "NPM_TAG=latest" >> $GITHUB_ENV
-              fi
-            else
-              echo "Version did not change, skipping..."
-              echo "should_publish=false" >> $GITHUB_ENV
-            fi
-          fi
-
-      - name: Install Dependencies
-        if: env.should_publish == 'true'
-        run: npm install
-
-      - name: Publish to NPM
-        if: env.should_publish == 'true'
-        run: npm publish --access public --tag ${{ env.NPM_TAG }}
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+name: Publish to NPM
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+  workflow_dispatch:
+
+jobs:
+  publish_npm:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Ensure full commit history for version comparison
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 18
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Check if version changed
+        id: version_check
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "Manual trigger detected. Skipping version check."
+            NEW_VERSION=$(jq -r '.version' package.json)
+            echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
+            echo "should_publish=true" >> $GITHUB_ENV
+            if [[ "$NEW_VERSION" == *"rc"* ]]; then
+              echo "This is a pre-release (next tag)."
+              echo "NPM_TAG=next" >> $GITHUB_ENV
+            else
+              echo "This is a stable release (latest tag)."
+              echo "NPM_TAG=latest" >> $GITHUB_ENV
+            fi
+          else
+            PREV_VERSION=$(git show HEAD~1:package.json | jq -r '.version' || echo "0.0.0")
+            NEW_VERSION=$(jq -r '.version' package.json)
+            echo "Previous version: $PREV_VERSION"
+            echo "New version: $NEW_VERSION"
+
+            if [ "$PREV_VERSION" != "$NEW_VERSION" ]; then
+              echo "Version changed, proceeding..."
+              echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
+              echo "should_publish=true" >> $GITHUB_ENV
+
+              # Detect pre-releases (versions with "rc" or similar tags)
+              if [[ "$NEW_VERSION" == *"rc"* ]]; then
+                echo "This is a pre-release (next tag)."
+                echo "NPM_TAG=next" >> $GITHUB_ENV
+              else
+                echo "This is a stable release (latest tag)."
+                echo "NPM_TAG=latest" >> $GITHUB_ENV
+              fi
+            else
+              echo "Version did not change, skipping..."
+              echo "should_publish=false" >> $GITHUB_ENV
+            fi
+          fi
+
+      - name: Install Dependencies
+        if: env.should_publish == 'true'
+        run: npm install
+
+      - name: Publish to NPM
+        if: env.should_publish == 'true'
+        run: npm publish --access public --tag ${{ env.NPM_TAG }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.lychee.toml

@@ -0,0 +1,26 @@
+verbose = true
+no_progress = true
+max_concurrency = 4
+exclude_mail = true
+
+# Network tuning
+timeout = 20            # seconds per request
+retries = 3             # retry transient failures
+retry_wait_time = 2     # seconds between retries
+max_redirects = 10
+user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36"
+
+# Treat rate-limiting as non-fatal in CI
+accept = [429]
+
+# Only check web links
+scheme = ["https", "http"]
+
+# Ignore common local/test URLs
+exclude = [
+  "^https?://localhost",
+  "^http://127\\.0\\.0\\.1",
+  "^https?://0\\.0\\.0\\.0",
+  "^file://"
+]
+

package/.markdownlint.json

@@ -0,0 +1,21 @@
+{
+  "default": true,
+  // Allow long lines; Prettier handles wrapping policy
+  "MD013": false,
+  // Allow inline HTML when needed
+  "MD033": false,
+  // First line need not be a top-level heading (many docs start with badges)
+  "MD041": false,
+  // Use fenced code blocks consistently (matches Prettier)
+  "MD046": { "style": "fenced" },
+  // Duplicate headings only matter among siblings
+  "MD024": { "siblings_only": true },
+  // Accept ascending ordered list numbers (matches Prettier behavior)
+  "MD029": { "style": "ordered" },
+  // Permit bare URLs; Prettier won’t auto-wrap, and link checks are handled separately
+  "MD034": false,
+  // Allow exactly one blank line between blocks (Prettier’s behavior)
+  "MD012": { "maximum": 1 },
+  // Don’t flag the two trailing spaces used for hard line breaks in Markdown
+  "MD009": { "strict": false }
+}

package/.markdownlintignore

@@ -0,0 +1,8 @@
+node_modules/
+.git/
+Library/
+obj/
+Temp/
+Samples~/
+/.github/
+

package/.pre-commit-config.yaml

@@ -1,22 +1,39 @@
-repos:
-  - repo: local
-    hooks:
-      - id: dotnet-tool-restore
-        name: Install .NET tools
-        entry: dotnet tool restore
-        language: system
-        always_run: true
-        pass_filenames: false
-        stages:
-          - pre-commit
-          - pre-push
-          - post-checkout
-          - post-rewrite
-        description: Install the .NET tools listed at .config/dotnet-tools.json.
-      - id: csharpier
-        name: Run CSharpier on C# files
-        entry: dotnet tool run Csharpier format
-        language: system
-        types:
-          - c#
-        description: CSharpier is an opinionated C# formatter inspired by Prettier.
+repos:
+  - repo: local
+    hooks:
+      - id: dotnet-tool-restore
+        name: Install .NET tools
+        entry: dotnet tool restore
+        language: system
+        always_run: true
+        pass_filenames: false
+        stages:
+          - pre-commit
+          - pre-push
+          - post-checkout
+          - post-rewrite
+        description: Install the .NET tools listed at .config/dotnet-tools.json.
+      - id: csharpier
+        name: Run CSharpier on C# files
+        entry: dotnet tool run Csharpier format
+        language: system
+        types:
+          - c#
+        description: CSharpier is an opinionated C# formatter inspired by Prettier.
+
+  - repo: local
+    hooks:
+      - id: prettier
+        name: Prettier (Markdown, JSON, asmdef, asmref)
+        entry: npx --yes prettier --write
+        language: system
+        files: '(?i)\.(md|markdown|json|asmdef|asmref)$'
+        description: Use the repo's Prettier version from package.json.
+
+  - repo: local
+    hooks:
+      - id: markdownlint
+        name: markdownlint (respect repo config)
+        entry: npx --yes markdownlint --config .markdownlint.json --ignore-path .markdownlintignore
+        language: system
+        files: '(?i)\.(md|markdown)$'

package/.prettierignore

@@ -0,0 +1,22 @@
+# Node / tooling
+node_modules/
+
+# Unity / build artifacts
+Library/
+obj/
+Temp/
+Logs/
+
+# GitHub
+.github/
+
+# Samples and external content
+Samples~/
+
+# Only format supported text/assets; Prettier globbing will still be constrained by scripts
+**/*.meta
+**/*.unity
+**/*.prefab
+**/*.mat
+**/*.asset
+

package/.prettierrc.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "none",
+  "bracketSpacing": true,
+  "proseWrap": "preserve",
+  "endOfLine": "crlf",
+  "overrides": [
+    {
+      "files": ["*.asmdef", "*.asmref"],
+      "options": {
+        "parser": "json"
+      }
+    }
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,52 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `Runtime/`: Runtime C# libraries (assembly definitions per area).
+- `Editor/`: Editor-only tooling and UIElements/USS.
+- `Tests/Runtime`, `Tests/Editor`: NUnit/UTF tests mirroring source folders (e.g., `Attributes`, `Extensions`).
+- `Shaders/`, `Styles/`, `URP/`: Rendering assets with accompanying `.meta` files.
+- `Docs/` and top-level guides: Developer guides and references.
+- `package.json`: Unity package metadata + helper scripts; `.editorconfig` defines formatting.
+
+## Build, Test, and Development Commands
+
+- Install hooks and tools: `npm run hooks:install` and `dotnet tool restore`.
+- Format C#: `dotnet tool run CSharpier format` (pre-commit runs this automatically).
+- Lint docs links: `npm run lint:docs` or `pwsh ./scripts/lint-doc-links.ps1 -VerboseOutput`.
+- Run tests (Unity): add this package to a Unity 2021.3+ project, then use Test Runner (EditMode/PlayMode). CLI example:
+  `Unity -batchmode -projectPath <Project> -runTests -testPlatform EditMode -testResults ./TestResults.xml -quit`.
+
+## Coding Style & Naming Conventions
+
+- Indentation: 4 spaces for `*.cs`; 2 spaces for JSON/YAML/`*.asmdef`.
+- Line endings: CRLF; UTF-8 BOM per `.editorconfig`.
+- C#: explicit types over `var`; braces required; `using` inside namespace.
+- Naming: PascalCase for types/public members; camelCase for fields/locals; interfaces prefixed `I` (e.g., `IResolver`); type params prefixed `T`; events start with `On...`.
+- Do not use underscores in function names, especially test function names.
+- Do not use regions, anywhere, ever.
+
+## Testing Guidelines
+
+- Frameworks: NUnit + Unity Test Framework (`[Test]`, `[UnityTest]`).
+- Structure tests to mirror `Runtime/` and `Editor/`; name files `*Tests.cs` (e.g., `Tests/Editor/MultiFileSelectorElementTests.cs`).
+- Keep tests deterministic; prefer fast EditMode where possible. Long-running tests should use timeouts (see `Tests/Runtime/RuntimeTestTimeouts.cs`).
+- Do not use regions.
+- Try to use minimal comments and instead rely on expressive naming conventions and assertions.
+- Do not use Description annotations for tests.
+
+## Commit & Pull Request Guidelines
+
+- Commits: short, imperative summaries (e.g., “Fix JSON serialization for FastVector”), group related changes.
+- PRs: clear description, link issues (`#123`), include before/after screenshots for editor UI, update relevant docs, and ensure tests + linters pass.
+- Version bumps in `package.json` should be deliberate and typically done in a release PR.
+
+## Security & Configuration Tips
+
+- Do not commit Unity `Library/`, `obj/`, or secrets; keep `.meta` files for assets.
+- Target Unity `2021.3`; verify `.asmdef` references when adding new namespaces.
+- NPM publishing uses GitHub Secrets; never commit tokens.
+
+## Agent-Specific Notes
+
+- This file’s scope is the entire repo. Keep changes minimal, follow `.editorconfig`, respect folder boundaries (Runtime vs Editor), and update docs/tests alongside code changes.

package/{Third Party Notices.md.meta → AGENTS.md.meta}

@@ -1,7 +1,7 @@
-fileFormatVersion: 2
-guid: 4908409161853e24bbbd3b2522b0fcc2
-TextScriptImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 676f5158fa37b694cb7f55fb0b061635
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/CHANGELOG.md.meta

@@ -1,7 +1,7 @@
-fileFormatVersion: 2
-guid: 1cc2c8be7f7467746a22e8b0a9b7da55
-TextScriptImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 1cc2c8be7f7467746a22e8b0a9b7da55
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: