@comty.io/core 0.1.3 → 0.1.5

package/README.md

@@ -2,6 +2,20 @@
 
 Comty's browser SDK provides shared comments and an element inspector, with no npm package dependencies.
 
+## Comment screenshots
+
+Posting immediately displays a pending comment and sends the JSON request. After the API confirms the save, the SDK captures and uploads the viewport separately. Screenshot failures do not roll back comments; save failures restore the draft for retry. Screenshot annotations reuse the real Comty pin and hover card (avatar, author, date and content). They are measured in an invisible, inert host, then cloned with their computed styles and embedded resources into the screenshot. The temporary host is removed after cloning and never appears on screen.
+
+The bundled capture engine is based on `html-to-image` 1.11.13 (MIT), not SnapDOM. It embeds web fonts, responsive images, CSS backgrounds and pseudo-elements, preserves scroll offsets, and yields during DOM traversal. Each font face keeps its source when selecting WOFF2, including consecutive subset and weight rules. Transparent page backgrounds are composited over the browser's light or dark canvas so the image viewer cannot tint the screenshot. Offscreen leaf boxes keep their layout dimensions without their rendering cost. PNG is preferred for text; large images fall back to JPEG. Captures are capped at 2× resolution / 2560 pixels per side and have a 15-second processing deadline.
+
+Resources are fetched directly first. Public cross-origin assets blocked by CORS can use `/api/sdk/capture-resource`, authenticated with the SDK token and restricted to the project's allowed domain. The API validates and pins public DNS addresses on every redirect, limits bytes/concurrency/time, and never forwards credentials to resource hosts. Deploy the API alongside the SDK to enable this fallback.
+
+The capture never locks or restyles the live page. If the URL, viewport or page scroll changes before cloning finishes, it skips that screenshot rather than attaching a mismatched image. Browser restrictions still apply to private resources, closed shadow roots and embedded frames; inaccessible frames retain an empty layout box. The final SVG serialization/rasterization still uses browser APIs on the main thread, so zero processing cost on every possible site cannot be guaranteed.
+
+`npm run build` reproducibly bundles the pinned library with small checked hooks for cooperative scheduling, resource fetching, cloning and exact font sizes; its MIT notice is included. No runtime package install is needed by SDK consumers. `npm run test:capture` runs Chrome/Chromium visual and posting tests; install Chromium with `npx playwright install chromium` on machines without Chrome. Comparison PNGs are written to `test-results/`.
+
+Visual tests disable screen-only LCD text antialiasing so the native reference and SVG/canvas capture use grayscale rendering. They reuse the comparator bundled with the pinned Playwright version and keep a 1% changed-pixel limit. Negative controls verify that missing fonts, images, comment markers and link underlines still fail; scrolled containers also have their own comparison region. CI uploads reference, capture and difference PNGs on failure. Review the comparator's internal imports when upgrading Playwright.
+
 ## Browser SDK
 
 ```sh
@@ -25,6 +39,10 @@ Element inspection shows a copyable CSS custom-property name above foreground/ba
 
 The toolbar pipette shows a circular nine-pixel magnifier from a local DOM snapshot, keeping the toolbar interactive with normal UI cursors. Its light/dark ring follows the sampled colour. Scrolling or resizing refreshes the snapshot. Inaccessible images, canvas/video, external fonts and live animations may differ from screen pixels; use native screen sampling for those. If a readable snapshot cannot be created, selection falls back to the element’s CSS colour. Shift-click the pipette in Chrome or Edge to sample screen pixels instead (including images). The screen pipette receives a pixel color and copies its HEX value. When an inspected element has an identifiable background token whose rendered color matches the sample, the toast shows that token as **Element token · --name**. The native pipette does not report which element produced the pixel, so the label describes the inspected element rather than attributing the sampled pixel. Matching variable values alone do not produce a label. No additional dependency is required.
 
+## Element inspector
+
+The dense inspector displays all collected properties without an expandable section, with color tokens and values sharing a line when space permits. Long selectors truncate at the beginning to preserve the final tag. The header copies the selector and all declarations; each property's copy icon copies its value and transitions to a check on success. Color and font values open their detail panels after selecting an element. Reduced-motion preferences disable the icon transition. Placement prefers below the target, then either side, then above; when no outside space fits, it minimizes overlap while staying in the viewport. Run `npm run test:inspector` for browser coverage of these interactions.
+
 ## Border measurements
 
 Open inspection with **Shift I**, then choose the ruler tool or press **R**. Move close to an element or page border: a red point marks the snapped start and the cursor shows the measurement axis. Drag to another border to measure its distance. Horizontal borders produce vertical measurements; side borders produce horizontal measurements. Releasing away from a border keeps the endpoint at that page position.