@comty.io/core 0.1.9 → 0.1.10

package/README.md

@@ -12,7 +12,13 @@ Target matching combines content, attributes and surrounding structure. Small ch
 
 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.
 
-Run `npm run test:anchors` for route, reload, ambiguity and overlay regressions.
+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
 
@@ -143,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.