Merge branch 'main' into matt/fe-1103-harden-assets-cursor-pagination-in-flight-tracking

Resolves a semantic conflict that no textual conflict surfaced: main taught
the flat-output pager to treat an empty-string next_cursor as a real cursor
(after: '') rather than falling back to offset paging, while this branch had
rewritten the refresh path around `page.next_cursor || undefined`, which
collapses '' back to undefined.

Adopts main's semantics in the refresh path so the cursor it seeds survives
into the subsequent loadMore, keeping main's
"threads an empty-string cursor into after instead of falling back to offset"
coverage green in the merged result.

Author: mattmillerai

.agents/checks/adr-compliance.md

@@ -33,15 +33,15 @@ Flag:
 - **New circular entity dependencies** — New circular imports between `LGraph` ↔ `Subgraph`, `LGraphNode` ↔ `LGraphCanvas`, or similar entity classes.
 - **Direct `graph._version++`** — Mutating the private version counter directly instead of through a public API. Extensions already depend on this side-channel; it must become a proper API.
 
-### Centralized Registries and ECS-Style Access
+### Dedicated Stores and Data/Behavior Separation
 
-All entity data access should move toward centralized query patterns, not instance property access.
+Entity data lives in dedicated Pinia stores keyed by string IDs (`widgetValueStore`, `domWidgetStore`, `layoutStore`, `nodeOutputStore`, `subgraphNavigationStore`, `previewExposureStore`), not on entity instances.
 
 Flag:
 
-- **New instance method/property patterns** — Adding `node.someProperty` or `node.someMethod()` for data that should be a component in the World, queried via `world.getComponent(entityId, ComponentType)`.
+- **New instance method/property patterns** — Adding `node.someProperty` or `node.someMethod()` for data that belongs in a dedicated store (e.g. widget values → `widgetValueStore` keyed by `WidgetId`).
 - **OOP inheritance for entity modeling** — Extending entity classes with new subclasses instead of composing behavior through components and systems.
-- **Scattered state** — New entity state stored in multiple locations (class properties, stores, local variables) instead of being consolidated in the World or in a single store.
+- **Duplicated authority** — Storing the same entity state in both a class property and a store, or across two stores, so ownership becomes ambiguous. Each piece of state should have one owning store.
 
 ### Extension Ecosystem Impact
 

.agents/checks/pattern-compliance.md

@@ -22,6 +22,7 @@ Steps:
 - Explicit return types on exported functions
 - Use `es-toolkit` for utility functions, NOT lodash. Flag any new `import ... from 'lodash'` or `import ... from 'lodash/*'`
 - Never use `z.any()` in Zod schemas — use `z.unknown()` and narrow
+- Never hand-declare or duplicate server/API response types locally — flag any local interface/type that reimplements a type already generated from an OpenAPI spec (e.g. `@comfyorg/ingest-types`, `@comfyorg/registry-types` in `packages/`) instead of importing it. This caused real bugs in PR #14771 (see `docs/guidance/typescript.md`)
 
 ### Vue (if applicable)
 

.agents/checks/playwright-e2e.md

@@ -7,12 +7,20 @@ tools: [Read, Grep]
 
 You are reviewing Playwright E2E test code in `browser_tests/`. Focus on issues a **reviewer** would catch that an author might miss — flakiness risks, fixture misuse, test isolation problems, and convention violations.
 
+**Rulebook — single source of truth:** `browser_tests/README.md` is the canonical
+browser-test guide. Every rule below is enforced against it; when in doubt, read
+that file. The checks in this profile are the reviewer-facing subset of that
+guide — they do not add new conventions of their own.
+
 Reference docs (read if you need full context):
 
-- `browser_tests/README.md` — setup, patterns, screenshot workflow
-- `browser_tests/AGENTS.md` — directory structure, fixture overview
-- `docs/guidance/playwright.md` — type assertion rules, test tags, forbidden patterns
-- `.claude/skills/writing-playwright-tests/SKILL.md` — anti-patterns, retry patterns, Vue Nodes vs LiteGraph decision guide
+- **`browser_tests/README.md`** — canonical guide: setup, directory structure,
+  writing conventions, typed mocks, flake prevention, screenshot workflow
+- `.claude/skills/writing-playwright-tests/SKILL.md` — authoring anti-patterns,
+  retry patterns, Vue Nodes vs LiteGraph decision guide
+- `.claude/skills/hardening-flaky-e2e-tests/SKILL.md` — flake transforms
+- `browser_tests/AGENTS.md` and `docs/guidance/playwright.md` are stubs that
+  redirect to the canonical guide
 
 ## Checks
 
@@ -47,9 +55,9 @@ Reference docs (read if you need full context):
 
 ### Convention Violations (Minor)
 
-11. **Missing test tags** — Every `test.describe` should have `tag` with at least one of: `@smoke`, `@slow`, `@screenshot`, `@canvas`, `@node`, `@widget`, `@mobile`, `@2x`. See `.claude/skills/writing-playwright-tests/SKILL.md` for when to use each.
+11. **Missing project-routing tags** — Project-routing tags are load-bearing: `playwright.config.ts` selects which project/run a test lands in by grepping `@mobile`, `@2x`, `@0.5x`, `@perf`, `@audit`, `@cloud`, `@oss`. A test that must run in one of those projects but lacks the tag silently won't run there. Organizational tags (`@smoke`, `@slow`, `@screenshot`, `@canvas`, `@node`, `@widget`, `@vue-nodes`, `@subgraph`, `@ui`) are for `--grep` filtering and are encouraged but not mandatory. See `browser_tests/README.md` → Test Tags.
 
-12. **`as any` type assertions** — Forbidden in E2E tests. Use specific type assertions or test-local type helpers. See `docs/guidance/playwright.md` for acceptable patterns.
+12. **`as any` type assertions** — Forbidden in E2E tests. Use specific type assertions or test-local type helpers. See `browser_tests/README.md` → Type safety for acceptable patterns.
 
 13. **Screenshot tests without masking dynamic content** — Timestamps, version numbers, or other non-deterministic content in screenshots will cause flakes. Use `mask` option.
 
@@ -65,10 +73,22 @@ Reference docs (read if you need full context):
 
 18. **Vue Nodes / LiteGraph mismatch** — If testing Vue-rendered node UI (DOM widgets, CSS states), should use `comfyPage.vueNodes.*`. If testing canvas interactions/connections, should use `comfyPage.nodeOps.*`. Mixing both in one test is a smell.
 
+### Structure, Types & Regressions (Medium)
+
+19. **Non-test code inline in the spec** — Flag free-standing functions/constants at the top of a spec that do setup, wire locators, or drive reusable dialog interactions (e.g. a "close the templates dialog" helper). These belong in `browser_tests/fixtures/components/` (page objects), `fixtures/helpers/`, or a Playwright fixture. Do NOT flag top-level Playwright hooks or configuration — `test.use()`, `test.describe.configure()`, and file-level `test.beforeEach()`/`test.afterEach()` legitimately live in the spec. The target is free-standing helpers/constants/locator wiring, not Playwright's own API surface. See `browser_tests/README.md` → Test structure.
+
+20. **Inline-declared types in specs/mocks** — Never hand-write `interface`/`type` shapes for API payloads, node definitions, or store data inside a spec or mock file. Must import the real type — generated packages (`@comfyorg/ingest-types`, `@comfyorg/registry-types`, `generatedManagerTypes.ts`) or `src/` Zod schemas. This requirement also applies to typed mock/data factories under `browser_tests/fixtures/data/` — the imported-type rule is enforced there despite the general `browser_tests/fixtures/` exclusion below. See `browser_tests/README.md` → Type safety and Test Data & Typed Mocks.
+
+21. **Spec not nested in a feature folder** — New specs must live in a `tests/` subfolder mirroring the feature under test, not dumped at the top level of `tests/`. Flag new top-level `browser_tests/tests/*.spec.ts` additions. See `browser_tests/README.md` → Spec File Placement.
+
+22. **Stale spec filename** — A spec's filename must describe the coverage it actually holds. Flag renamed/rescoped tests whose filename no longer matches their content. See `browser_tests/README.md` → Spec File Placement.
+
+23. **Test edit that may undo a prior fix** — When a diff removes or weakens an existing assertion, wait, or timeout in a test, confirm the change isn't silently undoing a deliberate regression/flake fix. The author should have run a `git blame` regression-detection pass; a reviewer flags removals of load-bearing guards whose history shows they fixed a specific race or bug. See `browser_tests/README.md` → Before changing an existing test.
+
 ## Rules
 
 - Only review `.spec.ts` files and supporting code in `browser_tests/`
-- Do NOT flag patterns in fixture/helper code (`browser_tests/fixtures/`) — those are shared infrastructure with different rules
-- "Major" for flakiness risks (items 1-7), "medium" for fixture misuse (8-10), "minor" for convention violations (11-15), "nitpick" for test design (16-18)
+- Do NOT flag patterns in fixture/helper code (`browser_tests/fixtures/`) — those are shared infrastructure with different rules (exception: rule 20's imported-type requirement still applies to typed mock/data factories under `browser_tests/fixtures/data/`)
+- "Major" for flakiness risks (items 1-7), "medium" for fixture misuse (8-10), "minor" for convention violations (11-15), "nitpick" for test design (16-18), "medium" for structure/type/regression rules (19-23)
 - When flagging missing fixture usage (item 8), confirm the helper exists by checking the fixture code — don't assume
 - Existing tests that predate conventions are acceptable to modify but not required to fix

.agents/checks/test-quality.md

@@ -31,7 +31,8 @@ Rules:
 
 - Tests use **Vitest** (not Jest) — run with `pnpm test:unit`
 - Test files are **colocated**: `MyComponent.test.ts` next to `MyComponent.vue`
-- Use `@vue/test-utils` for component testing, `@pinia/testing` (`createTestingPinia`) for store tests
+- Use `@testing-library/vue` with `@testing-library/user-event` for new
+  component tests, and `@pinia/testing` (`createTestingPinia`) for store tests
 - Browser/E2E tests use **Playwright** in `browser_tests/` — run with `pnpm test:browser:local`
 - Mock composables using the singleton factory pattern inside `vi.mock()` — see `docs/testing/unit-testing.md` for the pattern
 - Never use `any` in test code either — proper typing applies to tests too

.agents/resume

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+node_major="$(tr -d '[:space:]' < "$repo_root/.nvmrc")"
+node_home="$HOME/.local/share/comfyui-frontend-node-v$node_major"
+export PATH="$node_home/bin:$PATH"
+
+[[ -x "$node_home/bin/node" && -x "$node_home/bin/pnpm" ]]
+expected_pnpm="$("$node_home/bin/node" -e "console.log(require(process.argv[1]).packageManager.split('@')[1])" "$repo_root/package.json")"
+actual_node="$("$node_home/bin/node" --version)"
+actual_pnpm="$("$node_home/bin/pnpm" --version)"
+
+[[ "$actual_node" == v"$node_major".* ]]
+[[ "$actual_pnpm" == "$expected_pnpm" ]]
+
+echo "Orb toolchain ready: Node.js $actual_node, pnpm $actual_pnpm"

.agents/setup

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+if [[ "${AMP_ORB:-}" == 1 ]]; then
+  gh auth setup-git
+
+  if ! command -v docker >/dev/null 2>&1 ||
+    ! command -v dockerd >/dev/null 2>&1; then
+    echo "Installing Docker"
+    sudo install -m 0755 -d /etc/apt/keyrings
+    sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
+      -o /etc/apt/keyrings/docker.asc
+    sudo chmod a+r /etc/apt/keyrings/docker.asc
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |
+      sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
+    sudo apt-get update
+    sudo apt-get install -y \
+      docker-ce \
+      docker-ce-cli \
+      containerd.io \
+      docker-buildx-plugin \
+      docker-compose-plugin
+  fi
+fi
+
+node_major="$(tr -d '[:space:]' < "$repo_root/.nvmrc")"
+node_home="$HOME/.local/share/comfyui-frontend-node-v$node_major"
+
+install_node() {
+  local architecture
+  case "$(uname -m)" in
+    x86_64) architecture=x64 ;;
+    aarch64 | arm64) architecture=arm64 ;;
+    *)
+      echo "Unsupported architecture: $(uname -m)" >&2
+      return 1
+      ;;
+  esac
+
+  local release_base="https://nodejs.org/dist/latest-v${node_major}.x"
+  local archive
+  archive="$(curl -fsSL "$release_base/SHASUMS256.txt" | awk -v architecture="$architecture" '$2 == "node-v" substr($2, 7, index($2, "-linux-") - 7) "-linux-" architecture ".tar.xz" { print $2 }')"
+  if [[ -z "$archive" ]]; then
+    echo "Could not resolve the latest Node.js v${node_major} release" >&2
+    return 1
+  fi
+
+  local temporary_directory
+  temporary_directory="$(mktemp -d)"
+  (
+    trap 'rm -rf "$temporary_directory"' EXIT
+    echo "Installing Node.js v${node_major}"
+    curl -fsSL "$release_base/$archive" -o "$temporary_directory/$archive"
+    curl -fsSL "$release_base/SHASUMS256.txt" -o "$temporary_directory/SHASUMS256.txt"
+    (
+      cd "$temporary_directory"
+      grep "  $archive$" SHASUMS256.txt | sha256sum --check --status
+    )
+    rm -rf "$node_home"
+    mkdir -p "$node_home"
+    tar -xJf "$temporary_directory/$archive" --strip-components=1 -C "$node_home"
+  )
+}
+
+if [[ ! -x "$node_home/bin/node" ]] ||
+  [[ "$($node_home/bin/node --version)" != v"$node_major".* ]]; then
+  install_node
+fi
+
+export PATH="$node_home/bin:$PATH"
+
+pnpm_version="$(node -p "require('$repo_root/package.json').packageManager.split('@')[1]")"
+if [[ ! -x "$node_home/bin/pnpm" ]] ||
+  [[ "$(pnpm --version 2>/dev/null || true)" != "$pnpm_version" ]]; then
+  echo "Installing pnpm $pnpm_version"
+  npm install --global --prefix "$node_home" "pnpm@$pnpm_version"
+fi
+
+mkdir -p "$HOME/.local/bin"
+for executable in node npm npx pnpm pnpx; do
+  ln -sfn "$node_home/bin/$executable" "$HOME/.local/bin/$executable"
+done
+
+echo "Installing workspace dependencies"
+pnpm install --frozen-lockfile
+
+echo "Installing Playwright Chromium and system dependencies"
+pnpm exec playwright install --with-deps chromium
+
+echo "Orb setup complete"
+node --version
+pnpm --version

.agents/skills/consolidating-test-setup/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: consolidating-test-setup
+description: Consolidates repeated test setup and teardown into the narrowest shared lifecycle owner. Use when test files repeat initialization, cleanup, environment management, fixtures, or equivalent test doubles.
+---
+
+# Consolidating test setup
+
+Move repeated test plumbing to the narrowest shared owner that can provide it
+reliably. Keep test files focused on behavior.
+
+## Principles
+
+### Prove the code is equivalent
+
+Repetition is evidence, not proof. Similar code may use different defaults,
+ordering, or lifetimes. Group candidates by behavior before treating them as
+duplicates.
+
+### Centralize invariants, not scenarios
+
+Shared setup should establish conditions that hold for every test in its scope.
+State that explains one scenario belongs with that scenario.
+
+### Use the narrowest owner
+
+Prefer the mechanism that already owns the lifecycle. Use runner configuration
+before hooks, scoped fixtures before global setup, and local setup for local
+requirements. Wider reuse is not better reuse.
+
+### Treat setup and teardown as one contract
+
+Define who creates state, how long it lives, and who releases it. Cleanup must
+finish even when a test fails. Tests must not depend on execution order or on
+another test's cleanup.
+
+A shared default should be deterministic and easy to override. Local exceptions
+must not weaken isolation elsewhere.
+
+### Subtract before abstracting
+
+Remove suspected cargo-cult setup and run the affected tests. A targeted pass
+only marks it provisionally unnecessary. Delete it after the complete relevant
+suite and runner-specific lifecycle checks pass. If a test fails, use the
+failure to identify the contract before designing shared setup.
+
+A helper must own a policy or lifecycle, or remove meaningful reader effort.
+Moving the same lines behind a new name is not an improvement.
+
+### Preserve test intent
+
+Do not hide state that matters to the behavior under test. Check history before
+removing synchronization or cleanup because it may guard a past regression.
+Preserve that guarantee even if the implementation changes.
+
+## Runner-specific guidance
+
+Load only the reference for the runner in use:
+
+- [`reference/vitest.md`](reference/vitest.md) for Vitest and similar
+  in-process unit-test runners
+- [`reference/playwright.md`](reference/playwright.md) for Playwright and
+  similar browser-test runners
+
+These references supplement the repository's testing guide. They do not replace
+it. Load both only when the task spans both runners.
+
+## Workflow
+
+### 1. Discover
+
+Read the runner configuration, setup files, fixtures, helpers, and test guidance.
+Count repeated lifecycle behavior and note the suites that use it.
+
+### 2. Classify
+
+For each candidate, record:
+
+- the state it owns
+- its lifetime and scope
+- whether it is an invariant or scenario detail
+- intentional differences between suites
+- behavior already supplied by the runner
+
+### 3. Challenge
+
+Remove the candidate and run every affected suite. Classify it as unnecessary,
+universal, common with exceptions, or suite-specific.
+
+Subagents may evaluate disjoint groups of suites. Require evidence and exception
+reports from each. Keep the design and integration decision in the parent task.
+
+### 4. Place
+
+Choose the required lifetime and scope first. Then use the simplest owner at
+that exact boundary:
+
+- native runner behavior that supports the required scope
+- existing shared setup, fixture, or hook
+- a focused helper or test double
+- the individual suite
+
+Do not move state to a broader owner because its mechanism appears earlier in
+the list.
+
+### 5. Migrate
+
+Move one responsibility at a time. Add the shared owner, then remove only the
+local code it replaces. Keep intentional exceptions and scenario setup visible.
+Avoid unrelated test rewrites.
+
+### 6. Prove
+
+Run affected tests, tests of the shared lifecycle, repository static checks, and
+the complete relevant suite. Measure before and after when the new behavior runs
+for every test. Use enough comparable samples to separate a real change from
+normal variance.
+
+## Report
+
+State the repeated contract, its new owner, retained exceptions, rejected
+alternatives, duplication removed, and validation results. Include performance
+evidence when shared setup could affect suite runtime.
+
+## Guardrails
+
+- Do not replace native runner behavior with a custom abstraction.
+- Do not widen setup scope without evidence.
+- Do not add a helper merely to move code.
+- Do not hide global mutable state behind helper indirection.
+- Do not trade visible test intent for shorter files.
+- Do not trust targeted tests alone after changing shared lifecycle behavior.