@rettangoli/vt 1.0.0-rc5 → 1.0.2

package/README.md

@@ -39,7 +39,7 @@ Behavior split:
 Use selectors to run only part of VT in both `screenshot` and `report`:
 
 - `folder`: matches specs by folder prefix under `vt/specs` (example: `components/forms`)
-- `group`: matches section page key from `vt.sections` (`title` for flat sections, `items[].title` for grouped sections)
+- `group`: matches derived section page key from `vt.sections` titles (`kebab-case(title)`)
 - `item`: matches a single spec path relative to `vt/specs` (with or without extension)
 
 Selector rules:
@@ -54,18 +54,18 @@ Examples:
 rtgl vt screenshot --folder components/forms
 
 # Only one section/group key from vt.sections
-rtgl vt screenshot --group components_basic
+rtgl vt screenshot --group components-basic
 
 # Only one spec item (extension optional)
 rtgl vt screenshot --item components/forms/login
 rtgl vt screenshot --item components/forms/login.html
 
 # Combine selectors (union)
-rtgl vt screenshot --group components_basic --item pages/home
+rtgl vt screenshot --group components-basic --item pages/home
 
 # Same selectors for report
 rtgl vt report --folder components/forms
-rtgl vt report --group components_basic
+rtgl vt report --group components-basic
 rtgl vt report --item components/forms/login
 ```
 
@@ -90,7 +90,7 @@ vt:
     width: 1280
     height: 720
   sections:
-    - title: components_basic
+    - title: Components Basic
       files: components
 ```
 
@@ -99,7 +99,8 @@ Notes:
 - `vt.sections` is required.
 - `vt.service` is optional. When set, VT starts the command before capture, waits for `vt.url`, then stops it after capture.
 - when `vt.service` is omitted and `vt.url` is set, VT expects that URL to already be running.
-- Section page keys (`title` for flat sections and group `items[].title`) allow only letters, numbers, `-`, `_`.
+- Section page keys are derived as `kebab-case(title)` for flat sections and group `items[].title`.
+- Derived section page keys must be unique case-insensitively.
 - `vt.viewport` supports object or array; each viewport requires `id`, `width`, `height`.
 - `vt.capture` is internal and must be omitted.
 - Viewport contract details: `docs/viewport-contract.md`.
@@ -117,18 +118,22 @@ Supported frontmatter keys per spec file:
 - `waitStrategy` (`networkidle` | `load` | `event` | `selector`)
 - `viewport` (object or array of viewport objects)
 - `skipScreenshot`
+- `skipInitialScreenshot`
 - `specs`
 - `steps`
 
 Step action reference:
 
 - `docs/step-actions.md`
-- canonical format is structured action objects (`- action: ...`), with legacy string/block forms still supported.
+- canonical format is structured action objects (`- action: ...`); legacy one-line string steps are not supported.
+- `action: select` accepts exactly one of `testId` or `selector` for interaction targeting.
 - `assert` supports `js` deep-equal checks for object/array values.
 
 Screenshot naming:
 
-- First screenshot is `-01`.
+- By default, VT takes an immediate first screenshot before running `steps`.
+- Set `skipInitialScreenshot: true` in frontmatter to skip that immediate first screenshot.
+- First captured screenshot is `-01`.
 - Then `-02`, `-03`, up to `-99`.
 - When viewport id is configured, filenames include `--<viewportId>` before ordinal (for example `pages/home--mobile-01.webp`).
 
@@ -137,15 +142,15 @@ Screenshot naming:
 A pre-built Docker image with `rtgl` and Playwright browsers is available:
 
 ```bash
-docker pull han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc10
+docker pull han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27
 ```
 
 Run commands against a local project:
 
 ```bash
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc10 rtgl vt screenshot
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc10 rtgl vt report
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc10 rtgl vt accept
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt screenshot
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt report
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt accept
 ```
 
 Note:

package/bun.lock

@@ -0,0 +1,125 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "rviz",
+      "dependencies": {
+        "commander": "^13.1.0",
+        "js-yaml": "^4.1.0",
+        "liquidjs": "^10.21.0",
+        "pixelmatch": "^7.1.0",
+        "playwright": "^1.52.0",
+        "shiki": "^3.3.0"
+      }
+    }
+  },
+  "packages": {
+    "@shikijs/core": ["@shikijs/core@3.3.0", "", { "dependencies": { "@shikijs/types": "3.3.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.5" } }, "sha512-CovkFL2WVaHk6PCrwv6ctlmD4SS1qtIfN8yEyDXDYWh4ONvomdM9MaFw20qHuqJOcb8/xrkqoWQRJ//X10phOQ=="],
+
+    "@shikijs/engine-javascript": ["@shikijs/engine-javascript@3.3.0", "", { "dependencies": { "@shikijs/types": "3.3.0", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.2.0" } }, "sha512-XlhnFGv0glq7pfsoN0KyBCz9FJU678LZdQ2LqlIdAj6JKsg5xpYKay3DkazXWExp3DTJJK9rMOuGzU2911pg7Q=="],
+
+    "@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@3.3.0", "", { "dependencies": { "@shikijs/types": "3.3.0", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-l0vIw+GxeNU7uGnsu6B+Crpeqf+WTQ2Va71cHb5ZYWEVEPdfYwY5kXwYqRJwHrxz9WH+pjSpXQz+TJgAsrkA5A=="],
+
+    "@shikijs/langs": ["@shikijs/langs@3.3.0", "", { "dependencies": { "@shikijs/types": "3.3.0" } }, "sha512-zt6Kf/7XpBQKSI9eqku+arLkAcDQ3NHJO6zFjiChI8w0Oz6Jjjay7pToottjQGjSDCFk++R85643WbyINcuL+g=="],
+
+    "@shikijs/themes": ["@shikijs/themes@3.3.0", "", { "dependencies": { "@shikijs/types": "3.3.0" } }, "sha512-tXeCvLXBnqq34B0YZUEaAD1lD4lmN6TOHAhnHacj4Owh7Ptb/rf5XCDeROZt2rEOk5yuka3OOW2zLqClV7/SOg=="],
+
+    "@shikijs/types": ["@shikijs/types@3.3.0", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-KPCGnHG6k06QG/2pnYGbFtFvpVJmC3uIpXrAiPrawETifujPBv0Se2oUxm5qYgjCvGJS9InKvjytOdN+bGuX+Q=="],
+
+    "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
+
+    "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
+
+    "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
+
+    "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
+
+    "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
+
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
+    "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
+
+    "character-entities-html4": ["character-entities-html4@2.1.0", "", {}, "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA=="],
+
+    "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
+
+    "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
+
+    "commander": ["commander@13.1.0", "", {}, "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw=="],
+
+    "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
+
+    "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
+
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
+    "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
+
+    "hast-util-whitespace": ["hast-util-whitespace@3.0.0", "", { "dependencies": { "@types/hast": "^3.0.0" } }, "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw=="],
+
+    "html-void-elements": ["html-void-elements@3.0.0", "", {}, "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg=="],
+
+    "js-yaml": ["js-yaml@4.1.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA=="],
+
+    "liquidjs": ["liquidjs@10.21.0", "", { "dependencies": { "commander": "^10.0.0" }, "bin": { "liquidjs": "bin/liquid.js", "liquid": "bin/liquid.js" } }, "sha512-DouqxNU2jfoZzb1LinVjOc/f6ssitGIxiDJT+kEKyYqPSSSd+WmGOAhtWbVm1/n75svu4aQ+FyQ3ctd3wh1bbw=="],
+
+    "mdast-util-to-hast": ["mdast-util-to-hast@13.2.0", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "@ungap/structured-clone": "^1.0.0", "devlop": "^1.0.0", "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA=="],
+
+    "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
+
+    "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
+
+    "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
+
+    "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
+
+    "micromark-util-types": ["micromark-util-types@2.0.2", "", {}, "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA=="],
+
+    "oniguruma-parser": ["oniguruma-parser@0.12.1", "", {}, "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w=="],
+
+    "oniguruma-to-es": ["oniguruma-to-es@4.3.3", "", { "dependencies": { "oniguruma-parser": "^0.12.1", "regex": "^6.0.1", "regex-recursion": "^6.0.2" } }, "sha512-rPiZhzC3wXwE59YQMRDodUwwT9FZ9nNBwQQfsd1wfdtlKEyCdRV0avrTcSZ5xlIvGRVPd/cx6ZN45ECmS39xvg=="],
+
+    "pixelmatch": ["pixelmatch@7.1.0", "", { "dependencies": { "pngjs": "^7.0.0" }, "bin": { "pixelmatch": "bin/pixelmatch" } }, "sha512-1wrVzJ2STrpmONHKBy228LM1b84msXDUoAzVEl0R8Mz4Ce6EPr+IVtxm8+yvrqLYMHswREkjYFaMxnyGnaY3Ng=="],
+
+    "playwright": ["playwright@1.52.0", "", { "dependencies": { "playwright-core": "1.52.0" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-JAwMNMBlxJ2oD1kce4KPtMkDeKGHQstdpFPcPH3maElAXon/QZeTvtsfXmTMRyO9TslfoYOXkSsvao2nE1ilTw=="],
+
+    "playwright-core": ["playwright-core@1.52.0", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-l2osTgLXSMeuLZOML9qYODUQoPPnUsKsb5/P6LJ2e6uPKXUdPK5WYhN4z03G+YNbWmGDY4YENauNu4ZKczreHg=="],
+
+    "pngjs": ["pngjs@7.0.0", "", {}, "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow=="],
+
+    "property-information": ["property-information@7.0.0", "", {}, "sha512-7D/qOz/+Y4X/rzSB6jKxKUsQnphO046ei8qxG59mtM3RG3DHgTK81HrxrmoDVINJb8NKT5ZsRbwHvQ6B68Iyhg=="],
+
+    "regex": ["regex@6.0.1", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-uorlqlzAKjKQZ5P+kTJr3eeJGSVroLKoHmquUj4zHWuR+hEyNqlXsSKlYYF5F4NI6nl7tWCs0apKJ0lmfsXAPA=="],
+
+    "regex-recursion": ["regex-recursion@6.0.2", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg=="],
+
+    "regex-utilities": ["regex-utilities@2.3.0", "", {}, "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng=="],
+
+    "shiki": ["shiki@3.3.0", "", { "dependencies": { "@shikijs/core": "3.3.0", "@shikijs/engine-javascript": "3.3.0", "@shikijs/engine-oniguruma": "3.3.0", "@shikijs/langs": "3.3.0", "@shikijs/themes": "3.3.0", "@shikijs/types": "3.3.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-j0Z1tG5vlOFGW8JVj0Cpuatzvshes7VJy5ncDmmMaYcmnGW0Js1N81TOW98ivTFNZfKRn9uwEg/aIm638o368g=="],
+
+    "space-separated-tokens": ["space-separated-tokens@2.0.2", "", {}, "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q=="],
+
+    "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
+
+    "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
+
+    "unist-util-is": ["unist-util-is@6.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw=="],
+
+    "unist-util-position": ["unist-util-position@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA=="],
+
+    "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="],
+
+    "unist-util-visit": ["unist-util-visit@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg=="],
+
+    "unist-util-visit-parents": ["unist-util-visit-parents@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0" } }, "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw=="],
+
+    "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
+
+    "vfile-message": ["vfile-message@4.0.2", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw=="],
+
+    "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
+
+    "liquidjs/commander": ["commander@10.0.1", "", {}, "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug=="]
+  }
+}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@rettangoli/vt",
-  "version": "1.0.0-rc5",
+  "version": "1.0.2",
   "description": "Rettangoli Visual Testing",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuusoft-org/rettangoli",
+    "directory": "packages/rettangoli-vt"
+  },
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",

package/src/capture/playwright-runner.js

@@ -359,10 +359,12 @@ export class PlaywrightRunner {
       }
       settleMs = nowMs() - settleStart;
 
-      const firstScreenshotStart = nowMs();
-      const firstScreenshotPath = await wrappedScreenshot(page, task.baseName);
-      initialScreenshotMs = nowMs() - firstScreenshotStart;
-      console.log(`Screenshot saved: ${firstScreenshotPath}`);
+      if (!task.frontMatter?.skipInitialScreenshot) {
+        const firstScreenshotStart = nowMs();
+        const firstScreenshotPath = await wrappedScreenshot(page, task.baseName);
+        initialScreenshotMs = nowMs() - firstScreenshotStart;
+        console.log(`Screenshot saved: ${firstScreenshotPath}`);
+      }
 
       const stepsStart = nowMs();
       const stepsExecutor = createSteps(page, {

package/src/cli/report.js

@@ -2,10 +2,11 @@ import fs from "fs";
 import path from "path";
 import crypto from "crypto";
 import { cp } from "node:fs/promises";
+import { load as loadYaml } from "js-yaml";
 import pixelmatch from "pixelmatch";
 import sharp from "sharp";
-import { readYaml } from "../common.js";
-import { validateVtConfig } from "../validation.js";
+import { extractFrontMatter, readYaml } from "../common.js";
+import { validateFiniteNumber, validateVtConfig } from "../validation.js";
 import { resolveReportOptions } from "./report-options.js";
 import {
   buildAllRelativePaths,
@@ -17,6 +18,7 @@ import {
   filterRelativeScreenshotPathsBySelectors,
   hasSelectors,
 } from "../selector-filter.js";
+import { stripViewportSuffix } from "../viewport.js";
 
 const libraryTemplatesPath = new URL("./templates", import.meta.url).pathname;
 
@@ -35,6 +37,64 @@ function getAllFiles(dir, fileList = []) {
   return fileList;
 }
 
+function normalizePathForLookup(filePath) {
+  return String(filePath)
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+}
+
+function toSpecItemKey(relativeSpecPath) {
+  const normalized = normalizePathForLookup(relativeSpecPath);
+  const ext = path.extname(normalized);
+  return normalized.slice(0, normalized.length - ext.length);
+}
+
+function toScreenshotItemKey(relativeScreenshotPath) {
+  const normalized = normalizePathForLookup(relativeScreenshotPath).replace(/\.webp$/i, "");
+  const withoutOrdinal = normalized.replace(/-\d{1,3}$/i, "");
+  return stripViewportSuffix(withoutOrdinal);
+}
+
+function loadFrontMatterDiffThresholdOverrides(specsDir) {
+  const overrides = new Map();
+  if (!fs.existsSync(specsDir)) {
+    return overrides;
+  }
+
+  const specFiles = getAllFiles(specsDir);
+  for (const specFilePath of specFiles) {
+    const fileContent = fs.readFileSync(specFilePath, "utf8");
+    const { frontMatter } = extractFrontMatter(fileContent);
+    if (!frontMatter) {
+      continue;
+    }
+
+    const relativePath = path.relative(specsDir, specFilePath);
+    const frontMatterData = loadYaml(frontMatter);
+    if (
+      frontMatterData === null
+      || frontMatterData === undefined
+      || typeof frontMatterData !== "object"
+      || Array.isArray(frontMatterData)
+    ) {
+      continue;
+    }
+
+    if (frontMatterData.diffThreshold === undefined || frontMatterData.diffThreshold === null) {
+      continue;
+    }
+
+    validateFiniteNumber(
+      frontMatterData.diffThreshold,
+      `${relativePath}: frontMatter.diffThreshold`,
+      { min: 0, max: 100 },
+    );
+    overrides.set(toSpecItemKey(relativePath), frontMatterData.diffThreshold);
+  }
+
+  return overrides;
+}
+
 async function calculateImageHash(imagePath) {
   const imageBuffer = fs.readFileSync(imagePath);
   const hash = crypto.createHash("md5").update(imageBuffer).digest("hex");
@@ -137,10 +197,19 @@ async function main(options = {}) {
   const templatePath = path.join(libraryTemplatesPath, "report.html");
   const outputPath = path.join(siteOutputPath, "report.html");
   const jsonReportPath = path.join(".rettangoli", "vt", "report.json");
+  const specsDir = path.join(vtPath, "specs");
+
+  let diffThresholdOverridesBySpec = new Map();
+  if (compareMethod === "pixelmatch") {
+    diffThresholdOverridesBySpec = loadFrontMatterDiffThresholdOverrides(specsDir);
+  }
 
   console.log(`Comparison method: ${compareMethod}`);
   if (compareMethod === "pixelmatch") {
     console.log(`  color threshold: ${colorThreshold}, diff threshold: ${diffThreshold}%`);
+    if (diffThresholdOverridesBySpec.size > 0) {
+      console.log(`  frontmatter diff threshold overrides: ${diffThresholdOverridesBySpec.size}`);
+    }
   }
 
   if (!fs.existsSync(originalReferenceDir)) {
@@ -204,6 +273,9 @@ async function main(options = {}) {
       let error = false;
       let similarity = null;
       let diffPixels = null;
+      const itemKey = toScreenshotItemKey(relativePath);
+      const itemDiffThreshold = diffThresholdOverridesBySpec.get(itemKey);
+      const effectiveDiffThreshold = itemDiffThreshold ?? diffThreshold;
 
       if (candidateExists && referenceExists) {
         const diffDirPath = path.dirname(diffPath);
@@ -216,7 +288,7 @@ async function main(options = {}) {
           referencePath,
           compareMethod,
           diffPath,
-          { colorThreshold, diffThreshold },
+          { colorThreshold, diffThreshold: effectiveDiffThreshold },
         );
         if (comparison.error) {
           comparisonErrors.push(

package/src/cli/templates/default.html

@@ -3,8 +3,8 @@
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/base.css">
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/theme-rtgl-slate.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/base.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/theme-rtgl-slate.css">
     <script>
       window.rtglIcons = {
         text: `<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M4 12H20M4 8H20M4 16H12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
@@ -40,7 +40,7 @@
       }
     </script>
     <script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/rettangoli-iife-ui.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/rettangoli-iife-ui.min.js"></script>
     <script src="/public/main.js"></script>
   </head>
   <body class="dark">

package/src/cli/templates/index.html

@@ -4,8 +4,8 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/base.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/theme-rtgl-slate.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/base.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/theme-rtgl-slate.css">
   <script>
     window.addEventListener('DOMContentLoaded', () => {
       if (location.hash) {
@@ -17,7 +17,7 @@
     });
   </script>
   <script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/rettangoli-iife-ui.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/rettangoli-iife-ui.min.js"></script>
 
   <style>
     pre {

package/src/cli/templates/report.html

@@ -4,10 +4,10 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/base.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/themes/theme-rtgl-slate.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/base.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/themes/theme-rtgl-slate.css">
   <script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc6/dist/rettangoli-iife-ui.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/rettangoli-iife-ui.min.js"></script>
   <style>
     code {
       white-space: pre-wrap;

package/src/common.js

@@ -15,6 +15,7 @@ import path from "path";
 import { validateFiniteNumber, validateFrontMatter } from "./validation.js";
 import { createCaptureTasks } from "./capture/spec-loader.js";
 import { runCaptureScheduler } from "./capture/capture-scheduler.js";
+import { deriveSectionPageKey } from "./section-page-key.js";
 
 const removeExtension = (filePath) => filePath.replace(/\.[^/.]+$/, "");
 
@@ -248,7 +249,7 @@ function getContentType(filePath) {
 }
 
 function toSectionPageKey(sectionLike) {
-  return String(sectionLike.title || "").toLowerCase();
+  return deriveSectionPageKey(sectionLike);
 }
 
 /**

package/src/createSteps.js

@@ -160,7 +160,7 @@ function assertStructuredKeys(stepObject, allowedKeys, actionName) {
 
 function requireStepAction(stepObject) {
   if (!isPlainObject(stepObject)) {
-    throw new Error("Invalid step: expected string or object.");
+    throw new Error("Invalid step: expected an object.");
   }
   if (typeof stepObject.action !== "string" || stepObject.action.trim().length === 0) {
     throw new Error("Structured step requires non-empty string `action`.");
@@ -180,6 +180,27 @@ function requireStructuredString(stepObject, key, actionName) {
   return value;
 }
 
+function resolveStructuredSelectTarget(stepObject, actionName) {
+  const hasTestId = Object.prototype.hasOwnProperty.call(stepObject, "testId");
+  const hasSelector = Object.prototype.hasOwnProperty.call(stepObject, "selector");
+
+  if (hasTestId === hasSelector) {
+    throw new Error(`Structured action "${actionName}" requires exactly one of \`testId\` or \`selector\`.`);
+  }
+
+  if (hasTestId) {
+    return {
+      type: "testId",
+      value: requireStructuredString(stepObject, "testId", actionName),
+    };
+  }
+
+  return {
+    type: "selector",
+    value: requireStructuredString(stepObject, "selector", actionName),
+  };
+}
+
 function requireStructuredNumber(stepObject, key, actionName) {
   const value = stepObject[key];
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -224,13 +245,13 @@ function normalizeStructuredActionStep(stepObject) {
   }
 
   if (action === "select") {
-    assertStructuredKeys(stepObject, new Set(["action", "testId", "steps"]), action);
-    const testId = requireStructuredString(stepObject, "testId", action);
+    assertStructuredKeys(stepObject, new Set(["action", "testId", "selector", "steps"]), action);
+    const target = resolveStructuredSelectTarget(stepObject, action);
     if (!Array.isArray(stepObject.steps)) {
       throw new Error('Structured action "select" requires array `steps`.');
     }
     const nestedSteps = stepObject.steps.map((nestedStep) => normalizeStepValue(nestedStep));
-    return { kind: "block", command: "select", args: [testId], nestedSteps };
+    return { kind: "block", command: "select", args: [`${target.type}=${target.value}`], nestedSteps };
   }
 
   if (action === "click" || action === "dblclick" || action === "hover" || action === "rclick") {
@@ -411,12 +432,8 @@ function normalizeLegacyBlockStep(stepObject) {
 }
 
 function normalizeStepValue(step) {
-  if (typeof step === "string") {
-    const { command, args } = parseStepCommand(step);
-    return { kind: "command", command, args };
-  }
   if (!isPlainObject(step)) {
-    throw new Error("Invalid step: expected string or object.");
+    throw new Error("Invalid step: expected an object.");
   }
   if (Object.prototype.hasOwnProperty.call(step, "action")) {
     return normalizeStructuredActionStep(step);
@@ -832,22 +849,32 @@ async function assertStructured(page, assertionConfig, selectedElement) {
 }
 
 async function select(page, args) {
-  const testId = args[0];
-  if (!testId) {
-    throw new Error("`select` requires a test id.");
-  }
-  const hostElementLocator = page.getByTestId(testId);
-  
-  const interactiveElementLocator = hostElementLocator.locator(
-    'input, textarea, button, select, a'
-  ).first();
-  
+  const { named, positional } = parseNamedArgs(args);
+  const testId = typeof named.testId === "string" && named.testId.length > 0
+    ? named.testId
+    : positional[0];
+  const selector = typeof named.selector === "string" && named.selector.length > 0
+    ? named.selector
+    : undefined;
+
+  if ((testId ? 1 : 0) + (selector ? 1 : 0) !== 1) {
+    throw new Error("`select` requires exactly one target: `testId` or `selector`.");
+  }
+
+  const hostElementLocator = selector
+    ? page.locator(selector)
+    : page.getByTestId(testId);
+
+  const interactiveElementLocator = hostElementLocator
+    .locator('input, textarea, button, select, a')
+    .first();
+
   const count = await interactiveElementLocator.count();
-  
+
   if (count > 0) {
     return interactiveElementLocator;
   }
-  
+
   return hostElementLocator;
 }
 
@@ -890,11 +917,6 @@ export function createSteps(page, context) {
     if (!command) {
       return;
     }
-    if (command === "assert") {
-      throw new Error(
-        "Inline `assert` step strings are no longer supported. Use structured syntax: `- assert: { type: ..., ... }`.",
-      );
-    }
     const actionFn = actionHandlers[command];
     if (actionFn) {
       await actionFn(page, args, context, selectedElement);

package/src/section-page-key.js

@@ -0,0 +1,14 @@
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  return value.trim();
+}
+
+export function deriveSectionPageKey(sectionLike) {
+  return normalizeString(sectionLike?.title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/selector-filter.js

@@ -1,5 +1,6 @@
 import path from "path";
 import { stripViewportSuffix } from "./viewport.js";
+import { deriveSectionPageKey } from "./section-page-key.js";
 
 function toList(value) {
   if (value === undefined || value === null) return [];
@@ -25,7 +26,7 @@ export function normalizeSelectors(raw = {}) {
     .map(normalizePathValue)
     .filter((item) => item.length > 0);
   const groups = toList(raw.group)
-    .map((item) => String(item).trim().toLowerCase())
+    .map((item) => deriveSectionPageKey({ title: String(item) }))
     .filter((item) => item.length > 0);
   const items = toList(raw.item)
     .map(normalizeItemKey)
@@ -59,12 +60,12 @@ function resolveGroupFolders(configSections = [], groupSelectors = []) {
   for (const section of configSections) {
     if (section.type === "groupLabel" && Array.isArray(section.items)) {
       for (const item of section.items) {
-        groupFolderMap.set(String(item.title).toLowerCase(), normalizePathValue(item.files));
+        groupFolderMap.set(deriveSectionPageKey(item), normalizePathValue(item.files));
       }
       continue;
     }
     if (section.files) {
-      groupFolderMap.set(String(section.title).toLowerCase(), normalizePathValue(section.files));
+      groupFolderMap.set(deriveSectionPageKey(section), normalizePathValue(section.files));
     }
   }
 

package/src/validation.js

@@ -1,4 +1,5 @@
 import { normalizeViewportField } from "./viewport.js";
+import { deriveSectionPageKey } from "./section-page-key.js";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -121,8 +122,6 @@ const LEGACY_CAPTURE_FIELDS = {
   headless: true,
 };
 
-const SECTION_PAGE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
-
 function assertNoLegacyCaptureFields(vtConfig, sourcePath) {
   for (const legacyField of Object.keys(LEGACY_CAPTURE_FIELDS)) {
     if (Object.prototype.hasOwnProperty.call(vtConfig, legacyField)) {
@@ -133,14 +132,11 @@ function assertNoLegacyCaptureFields(vtConfig, sourcePath) {
   }
 }
 
-function assertValidSectionPageKey(value, path) {
-  assert(
-    typeof value === "string" && value.trim().length > 0,
-    `"${path}" is required.`,
-  );
+function assertDerivableSectionPageKey(sectionLike, path) {
+  const pageKey = deriveSectionPageKey(sectionLike);
   assert(
-    SECTION_PAGE_KEY_PATTERN.test(value),
-    `"${path}" must contain only letters, numbers, "-" or "_", and cannot include spaces.`,
+    pageKey.length > 0,
+    `"${path}" must contain at least one letter or number.`,
   );
 }
 
@@ -173,25 +169,25 @@ function validateSection(section, index) {
 
       assert(typeof item.title === "string" && item.title.trim().length > 0, `"${itemPath}.title" is required.`);
       assert(typeof item.files === "string" && item.files.trim().length > 0, `"${itemPath}.files" is required.`);
-      assertValidSectionPageKey(item.title, `${itemPath}.title`);
+      assertDerivableSectionPageKey(item, `${itemPath}.title`);
     });
     return;
   }
 
   validateOptionalString(section.files, `${sectionPath}.files`);
   assert(typeof section.files === "string" && section.files.trim().length > 0, `"${sectionPath}.files" is required.`);
-  assertValidSectionPageKey(section.title, `${sectionPath}.title`);
+  assertDerivableSectionPageKey(section, `${sectionPath}.title`);
 }
 
 function collectSectionPageKeys(vtConfig) {
   const keys = [];
   vtConfig.sections.forEach((section) => {
     if (section.type === "groupLabel" && Array.isArray(section.items)) {
-      section.items.forEach((item) => keys.push(item.title));
+      section.items.forEach((item) => keys.push(deriveSectionPageKey(item)));
       return;
     }
     if (section.files) {
-      keys.push(section.title);
+      keys.push(deriveSectionPageKey(section));
     }
   });
   return keys;
@@ -277,19 +273,22 @@ function validateStructuredActionStep(step, stepPath) {
   }
 
   if (action === "select") {
-    assertNoUnknownStepKeys(step, stepPath, new Set(["action", "testId", "steps"]));
+    assertNoUnknownStepKeys(step, stepPath, new Set(["action", "testId", "selector", "steps"]));
     validateOptionalString(step.testId, `${stepPath}.testId`);
+    validateOptionalString(step.selector, `${stepPath}.selector`);
     assert(
-      typeof step.testId === "string" && step.testId.trim().length > 0,
-      `"${stepPath}.testId" is required for action=select.`,
+      (
+        typeof step.testId === "string"
+        && step.testId.trim().length > 0
+      ) !== (
+        typeof step.selector === "string"
+        && step.selector.trim().length > 0
+      ),
+      `"${stepPath}" for action=select requires exactly one of "testId" or "selector".`,
     );
     assert(Array.isArray(step.steps), `"${stepPath}.steps" must be an array for action=select.`);
     step.steps.forEach((nestedStep, nestedIndex) => {
       const nestedPath = `${stepPath}.steps[${nestedIndex}]`;
-      if (typeof nestedStep === "string") {
-        assert(nestedStep.trim().length > 0, `"${nestedPath}" cannot be empty.`);
-        return;
-      }
       validateStepObject(nestedStep, nestedPath);
     });
     return;
@@ -434,7 +433,7 @@ function validateStructuredActionStep(step, stepPath) {
 }
 
 function validateStepObject(step, stepPath) {
-  assert(isPlainObject(step), `"${stepPath}" must be an object with one key or a string.`);
+  assert(isPlainObject(step), `"${stepPath}" must be an object.`);
 
   if (Object.prototype.hasOwnProperty.call(step, "action")) {
     validateStructuredActionStep(step, stepPath);
@@ -459,10 +458,6 @@ function validateStepObject(step, stepPath) {
   assert(Array.isArray(nestedSteps), `"${stepPath}.${stepKey}" must be an array of step values.`);
   nestedSteps.forEach((nestedStep, nestedIndex) => {
     const nestedPath = `${stepPath}.${stepKey}[${nestedIndex}]`;
-    if (typeof nestedStep === "string") {
-      assert(nestedStep.trim().length > 0, `"${nestedPath}" cannot be empty.`);
-      return;
-    }
     validateStepObject(nestedStep, nestedPath);
   });
 }
@@ -606,6 +601,10 @@ export function validateFrontMatter(frontMatter, specPath) {
     ["networkidle", "load", "event", "selector"],
   );
   validateOptionalBoolean(frontMatter.skipScreenshot, `${specPath}: frontMatter.skipScreenshot`);
+  validateOptionalBoolean(
+    frontMatter.skipInitialScreenshot,
+    `${specPath}: frontMatter.skipInitialScreenshot`,
+  );
 
   if (frontMatter.waitStrategy === "event") {
     assert(
@@ -633,10 +632,6 @@ export function validateFrontMatter(frontMatter, specPath) {
     assert(Array.isArray(frontMatter.steps), `"${specPath}: frontMatter.steps" must be an array.`);
     frontMatter.steps.forEach((step, index) => {
       const stepPath = `${specPath}: frontMatter.steps[${index}]`;
-      if (typeof step === "string") {
-        assert(step.trim().length > 0, `"${stepPath}" cannot be empty.`);
-        return;
-      }
       validateStepObject(step, stepPath);
     });
   }