@comty.io/core 0.1.8 → 0.1.10

package/README.md

@@ -10,17 +10,25 @@ Comments use the pathname and hash routes starting with `#/` or `#!/`. Plain fra
 
 Target matching combines content, attributes and surrounding structure. Small changes inside a container can preserve its comments; ambiguous matches do not place a pin. The sidebar shows **Target missing** when no target is found and **Target uncertain** when placement cannot be determined reliably. Both still open the full thread. Closed or unmounted known overlays do not count as deleted elements, and their comments never attach to matching content outside that overlay.
 
-Run `npm run test:anchors` for route, reload, ambiguity and overlay regressions.
+New anchors exclude editable content from inputs, textareas, selects and rich-text editors, including when comparing their surrounding containers. Repeated fields use their attributes and question context to distinguish them. React-generated IDs are not treated as permanent identities. Existing comments are resolved again on reload without rewriting their stored anchors.
+
+New comments also capture an automatic structural anchor, with no prototype annotations or Angular development APIs. Copy, classes, dimensions and layout wrappers can change without requiring an exact text match. The nearest small composition is compared after meaningful DOM changes, even when the target node is reused. A large structural change (for example an empty illustration/action replaced by a table) hides the pin; returning to that composition resolves it again. Unrelated page changes and list length changes are tolerated. The original anchor is never rewritten. Repeated records require distinguishing context after remount, and ambiguous twins stay in the sidebar rather than borrowing another record's pin.
+
+This is a conservative structural heuristic, not a semantic understanding of application data: states with indistinguishable markup cannot be reliably separated, and removing every distinguishing cue from repeated records can leave a comment uncertain. All comments use the same matching engine. Saved formats are normalized at read time without rewriting the original evidence. Older comments offer fewer clues: missing state fingerprints cannot be recovered, and position is not guaranteed when the remaining clues are ambiguous. Text contributes to confidence but is never a mandatory exact match.
+
+The dependency-free TypeScript engine lives in `src/resilient-anchor.ts`; `npm run build` generates its browser JavaScript and includes it in the CDN bundle. The same source is mirrored in Hephaistos' `src/modules/commentaires/resilient-anchor.ts`; update both copies together.
+
+Run `npm run test:anchors` for route, reload, rewritten copy, state transitions, repeated records, ambiguity and overlay regressions.
 
 ## 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.
+Posting immediately displays a pending comment, captures the viewport, then sends the comment and screenshot in one multipart request. The API stores the screenshot before creating the comment. Capture or save failures restore the draft for retry instead of silently creating a comment without an image. 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.
+The capture never locks or restyles the live page. If the URL, viewport or page scroll changes before cloning finishes, posting fails and restores the draft for retry 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/`.
 
@@ -141,3 +149,24 @@ In Inspect (**Shift I**), choose **Annotate** (**D**) to draw with a pencil, rec
 Choose **Capture area** (**S** while inspecting), then drag a rectangle in either direction to download a PNG. The image includes visible annotations, ruler strips, ruler guides, layout guides and distance measurements, without the toolbar or selection controls. **Escape** cancels. Captures stay local and use the existing DOM snapshot engine; inaccessible embedded pages and protected media may not appear exactly as rendered by the browser.
 
 The local Agent refreshes on entry and when returning to the tab. It polls only while tasks are pending or running; those progress checks do not reload shared comments. Inspector tools make no polling requests while idle.
+
+## UI style isolation
+
+Comty renders its tools, comments and dialogs inside a Shadow DOM. Client selectors
+(including resets and `!important` rules) do not style its internal controls.
+Inherited typography is reset at the UI root. `src/style.js` keeps the SDK's 16px
+rem design scale in source and resolves it to CSS pixels when emitting the private
+stylesheet: a shadow tree alone does **not** isolate `rem` from the client's `html`.
+Do not add root-relative sizes to inline styles or inject UI rules into the page.
+Only inspection cursors are intentionally document-scoped.
+
+The overlay uses the browser's top layer to escape transformed/clipped ancestors,
+and compensates ancestor CSS `zoom` without cancelling browser zoom. Native modal
+dialogs remain supported. Internal queries and focus checks use the shadow tree;
+document listeners resolve retargeted UI events through their composed path.
+
+Run `npm run test:isolation` for npm/CDN regressions against client resets, changed
+root sizes, RTL text, hostile host selectors, CSS zoom, transforms and modal dialogs.
+This runs in CI alongside interaction and screenshot checks. The Shadow DOM is a
+CSS boundary, not a security sandbox: client JavaScript can still remove the widget
+or block its resources. Top-layer isolation requires a browser with the Popover API.