From 5c631211b140fdf636e74514a73ab3191549c60b Mon Sep 17 00:00:00 2001 From: ameerf-wix Date: Wed, 20 May 2026 18:49:28 +0300 Subject: [PATCH 1/4] context7 registration plan --- .../context7_registration_91d783e5.plan.md | 169 ++++++++++++++++++ .../llms-txt_web_presence_c57a751b.plan.md | 10 +- 2 files changed, 174 insertions(+), 5 deletions(-) create mode 100644 .cursor/plans/context7_registration_91d783e5.plan.md diff --git a/.cursor/plans/context7_registration_91d783e5.plan.md b/.cursor/plans/context7_registration_91d783e5.plan.md new file mode 100644 index 00000000..790eead4 --- /dev/null +++ b/.cursor/plans/context7_registration_91d783e5.plan.md @@ -0,0 +1,169 @@ +--- +name: Context7 Registration +overview: Register @wix/interact on Context7 by creating a validated context7.json config file, then submitting and claiming the library through the Context7 web interface. +todos: + - id: create-context7-json + content: Create context7.json at repo root with validated schema-compliant config + status: pending + - id: submit-to-context7 + content: "Manual: submit github.com/wix/interact at context7.com/add-library" + status: pending + - id: claim-library + content: "Manual: claim library ownership on Context7 for admin panel access" + status: pending + - id: verify-index + content: "Manual: verify indexed content via resolve-library-id and query-docs MCP tools" + status: pending +isProject: false +--- + +# Context7 Registration for @wix/interact + +## Background + +Context7 is an MCP server that indexes library documentation from GitHub and serves it to AI agents on demand. Registering `@wix/interact` makes the package discoverable to every developer with Context7 configured. Context7 scrapes markdown from the repo; a `context7.json` at the repo root controls what gets indexed. + +### Comparable libraries already on Context7 + +- **GSAP** (`greensock/gsap`) -- 7,609 tokens, 66 snippets, Trust Score 6.8. Auto-indexed, no `context7.json`. +- **Motion for Vue** (`motiondivision/motion-vue`) -- 18,609 tokens, 149 snippets, Trust Score 8.0. Also auto-indexed. + +Neither competitor uses a `context7.json`, so `@wix/interact` can differentiate by providing precise folder scoping and agent rules to produce a higher-quality, lower-noise index. + +--- + +## What gets indexed + +### Rules files -- 7 files, 2,115 lines in [packages/interact/rules/](packages/interact/rules/) + +- `full-lean.md` (700 lines) -- comprehensive reference +- `integration.md` (334 lines) -- entry points, registerEffects, config schema +- `pointermove.md` (279 lines) +- `viewenter.md` (226 lines) +- `viewprogress.md` (196 lines) +- `hover.md` (191 lines) +- `click.md` (189 lines) + +### Docs directory -- 26 files, ~14,846 lines in [packages/interact/docs/](packages/interact/docs/) + +- `guides/` -- getting-started, triggers, effects, conditions, sequences, custom-elements, state-management, lists, configuration-structure +- `api/` -- interact-class, functions, types, interaction-controller, interact-element, element-selection +- `examples/` -- entrance-animations, hover-effects, click-interactions, list-patterns +- `integration/` -- react +- `advanced/` -- README (links to custom triggers, custom effects) + +### Package README -- [packages/interact/README.md](packages/interact/README.md) (385 lines) + +--- + +## What must NOT be indexed + +- Source code (`packages/interact/src/`, `packages/interact/test/`) +- Sibling packages (`packages/motion/`, `packages/motion-presets/`) +- Apps (`apps/` -- demo, docs, playground, website) +- CI/tooling (`.github/`, `.cursor/`, `.claude/`, `scripts/`) +- Internal root markdown: `AGENTS.md`, `CLAUDE.md` (symlink to AGENTS.md), `CONTRIBUTING.md`, `readme-spec-1.md`, `readme-spec-2.md` +- Default exclusions already handle: `CHANGELOG.md` + +--- + +## Schema constraints (from research) + +These constraints were discovered by reading the actual JSON Schema at `schema/context7.json` and confirmed via Context7 docs and GitHub issues: + +- **`rules` must be an array of strings**, each 5-200 characters. NOT a single string. +- **`excludeFiles` accepts filenames only** -- pattern `^[^/\\]+$`, no glob, no regex. `"*.ts"` is invalid. +- **`additionalProperties: false`** -- any unknown field fails validation. +- **Root-level markdown is always included** when `folders` is specified (confirmed behavior, narrowed to README.md only when folders are set). +- **Known `folders` bug** (issue #1020, Jan 2026) -- `folders` was not always respected. Belt-and-suspenders approach recommended: specify both `folders` (whitelist) AND `excludeFolders` (blacklist). + +--- + +## Deliverable: `context7.json` + +New file at repo root: [context7.json](context7.json) + +```json +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "@wix/interact", + "description": "Declarative animation library -- wire scroll, hover, click, and pointer triggers to effects via JSON config. Built on Web Animations API.", + "folders": [ + "packages/interact/rules", + "packages/interact/docs", + "packages/interact" + ], + "excludeFolders": [ + "packages/interact/src", + "packages/interact/test", + "packages/motion", + "packages/motion-presets", + "apps", + ".github", + ".cursor", + ".claude", + "scripts", + "node_modules", + "dist" + ], + "excludeFiles": [ + "AGENTS.md", + "CLAUDE.md", + "CONTRIBUTING.md", + "readme-spec-1.md", + "readme-spec-2.md" + ], + "rules": [ + "Start with rules/full-lean.md for the complete @wix/interact reference", + "For trigger-specific rules: click.md, hover.md, viewenter.md, viewprogress.md, pointermove.md", + "For integration patterns (React, vanilla JS, custom elements) use rules/integration.md", + "Always call registerEffects() before Interact.create()", + "Use generate() from @wix/interact/web for FOUC prevention with custom elements", + "Include a prefers-reduced-motion condition for accessibility" + ] +} +``` + +### Design decisions + +- **`folders` includes `packages/interact`** (not just `rules` and `docs`) so that `packages/interact/README.md` is explicitly in scope. The `excludeFolders` for `src/` and `test/` prevents source code from leaking. This is the belt-and-suspenders approach against the known `folders` bug. +- **`excludeFiles` lists exact filenames** -- no globs. Context7 only indexes markdown by default, so there is no need to filter `*.ts`, `*.js`, `*.css` etc. (which would be invalid anyway). The five listed files are root-level markdown that would otherwise pollute the index with internal agent instructions and spec drafts. +- **`rules` is an array of 6 strings**, each under 200 characters, referencing actual filenames that exist in the repo. This replaces the previous plans' single-string approach (which would fail schema validation). The rules guide agents to start with `full-lean.md` and drill into trigger-specific files as needed. +- **No `excludeFiles` globs** -- the previous detailed plan's `"*.ts"`, `"*.js"` entries would fail the schema's `^[^/\\]+$` pattern constraint. +- **Dropped `packages/interact-debug`** from excludeFolders -- this directory does not exist. + +--- + +## Manual steps (post-merge) + +### Submit the repository + +1. Go to `context7.com/add-library` +2. Paste: `https://github.com/wix/interact` +3. Context7 detects `context7.json` and applies the folder/exclude config +4. Verify the parsed result includes rules and docs content, not source code + +### Claim the library + +1. On the Context7 library page for `@wix/interact`, click "Claim" +2. Authenticate with GitHub +3. This unlocks the admin panel for editing config via web UI, managing team access, viewing usage analytics, and higher rate limits + +### Verify indexed content + +After indexing completes (typically minutes, review may take 1-3 business days): + +1. Use Context7 MCP tool: `resolve-library-id` with query `"@wix/interact"` -- expect ID `/wix/interact` +2. Fetch docs with the resolved ID and verify: + - `rules/full-lean.md` content is present and complete + - `rules/click.md` content is present + - `docs/guides/getting-started.md` is present + - Source code files (`src/core/Interact.ts` etc.) are NOT present + - `AGENTS.md` / `readme-spec-*.md` content is NOT present + - `packages/motion/` content is NOT present + +--- + +## Files touched + +- **NEW**: `context7.json` (repo root, ~35 lines) diff --git a/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md b/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md index a3e98315..4cba6d63 100644 --- a/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md +++ b/.cursor/plans/llms-txt_web_presence_c57a751b.plan.md @@ -7,19 +7,19 @@ todos: status: completed - id: workflow content: Update `.github/workflows/interactdocs.yml` -- run generation script and copy outputs to `_site/` - status: pending + status: completed - id: npm-ship content: Add `llms.txt` to `packages/interact/package.json` files array, add `.gitignore` entries for generated files - status: pending + status: completed - id: canonical-url content: Add canonical URL HTML comment to top of `full-lean.md` - status: pending + status: completed - id: root-script content: Add `generate:llms` script to root `package.json` - status: pending + status: completed - id: verify content: Run generation script locally and verify both outputs are correct - status: pending + status: completed isProject: false --- From b2c803418bf75d2be22bd05071690d9c318b034f Mon Sep 17 00:00:00 2001 From: ameerf-wix Date: Wed, 20 May 2026 19:10:56 +0300 Subject: [PATCH 2/4] prettier --- .cursor/plans/context7_registration_91d783e5.plan.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/.cursor/plans/context7_registration_91d783e5.plan.md b/.cursor/plans/context7_registration_91d783e5.plan.md index 790eead4..77dac7af 100644 --- a/.cursor/plans/context7_registration_91d783e5.plan.md +++ b/.cursor/plans/context7_registration_91d783e5.plan.md @@ -6,13 +6,13 @@ todos: content: Create context7.json at repo root with validated schema-compliant config status: pending - id: submit-to-context7 - content: "Manual: submit github.com/wix/interact at context7.com/add-library" + content: 'Manual: submit github.com/wix/interact at context7.com/add-library' status: pending - id: claim-library - content: "Manual: claim library ownership on Context7 for admin panel access" + content: 'Manual: claim library ownership on Context7 for admin panel access' status: pending - id: verify-index - content: "Manual: verify indexed content via resolve-library-id and query-docs MCP tools" + content: 'Manual: verify indexed content via resolve-library-id and query-docs MCP tools' status: pending isProject: false --- @@ -88,11 +88,7 @@ New file at repo root: [context7.json](context7.json) "$schema": "https://context7.com/schema/context7.json", "projectTitle": "@wix/interact", "description": "Declarative animation library -- wire scroll, hover, click, and pointer triggers to effects via JSON config. Built on Web Animations API.", - "folders": [ - "packages/interact/rules", - "packages/interact/docs", - "packages/interact" - ], + "folders": ["packages/interact/rules", "packages/interact/docs", "packages/interact"], "excludeFolders": [ "packages/interact/src", "packages/interact/test", From edd05904f57c9c30ef3cd7e1ce2b39c878a0c30d Mon Sep 17 00:00:00 2001 From: ameerf-wix Date: Mon, 25 May 2026 14:13:19 +0300 Subject: [PATCH 3/4] context7.json + update plan --- .../context7_registration_91d783e5.plan.md | 19 +++++----- context7.json | 36 +++++++++++++++++++ 2 files changed, 47 insertions(+), 8 deletions(-) create mode 100644 context7.json diff --git a/.cursor/plans/context7_registration_91d783e5.plan.md b/.cursor/plans/context7_registration_91d783e5.plan.md index 77dac7af..a6e06dde 100644 --- a/.cursor/plans/context7_registration_91d783e5.plan.md +++ b/.cursor/plans/context7_registration_91d783e5.plan.md @@ -4,7 +4,7 @@ overview: Register @wix/interact on Context7 by creating a validated context7.js todos: - id: create-context7-json content: Create context7.json at repo root with validated schema-compliant config - status: pending + status: completed - id: submit-to-context7 content: 'Manual: submit github.com/wix/interact at context7.com/add-library' status: pending @@ -72,6 +72,7 @@ Neither competitor uses a `context7.json`, so `@wix/interact` can differentiate These constraints were discovered by reading the actual JSON Schema at `schema/context7.json` and confirmed via Context7 docs and GitHub issues: - **`rules` must be an array of strings**, each 5-200 characters. NOT a single string. +- **`rules` purpose**: strings are injected verbatim into the LLM context alongside code snippets when `query-docs` is called. They are **usage guidelines for the coding agent**, not navigation hints for the indexer. Use imperative mood: "Use X", "Avoid Y". Common mistakes: navigation hints ("Start with file X"), vague/passive language ("You should try to..."), file-path references that only make sense to a human browsing the repo. - **`excludeFiles` accepts filenames only** -- pattern `^[^/\\]+$`, no glob, no regex. `"*.ts"` is invalid. - **`additionalProperties: false`** -- any unknown field fails validation. - **Root-level markdown is always included** when `folders` is specified (confirmed behavior, narrowed to README.md only when folders are set). @@ -87,7 +88,7 @@ New file at repo root: [context7.json](context7.json) { "$schema": "https://context7.com/schema/context7.json", "projectTitle": "@wix/interact", - "description": "Declarative animation library -- wire scroll, hover, click, and pointer triggers to effects via JSON config. Built on Web Animations API.", + "description": "Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic.", "folders": ["packages/interact/rules", "packages/interact/docs", "packages/interact"], "excludeFolders": [ "packages/interact/src", @@ -110,12 +111,14 @@ New file at repo root: [context7.json](context7.json) "readme-spec-2.md" ], "rules": [ - "Start with rules/full-lean.md for the complete @wix/interact reference", - "For trigger-specific rules: click.md, hover.md, viewenter.md, viewprogress.md, pointermove.md", - "For integration patterns (React, vanilla JS, custom elements) use rules/integration.md", "Always call registerEffects() before Interact.create()", - "Use generate() from @wix/interact/web for FOUC prevention with custom elements", - "Include a prefers-reduced-motion condition for accessibility" + "Use overflow: clip (not overflow: hidden) on all ancestors between source and scroll container for viewProgress", + "When viewEnter source and target are the same element, use type 'once' only — other types cause re-trigger loops", + "Separate source and target elements when hover or click effects change size or position to prevent hit-area flicker", + "Avoid same-element source/target with pointerMove hitArea:'self' and size-changing effects — causes jitter", + "Use trigger: 'activate' instead of 'click' to also handle keyboard activation (Enter/Space)", + "Call generate() from @wix/interact/web before page render for FOUC prevention with custom elements", + "Add prefers-reduced-motion conditions or set Interact.forceReducedMotion for accessibility" ] } ``` @@ -124,7 +127,7 @@ New file at repo root: [context7.json](context7.json) - **`folders` includes `packages/interact`** (not just `rules` and `docs`) so that `packages/interact/README.md` is explicitly in scope. The `excludeFolders` for `src/` and `test/` prevents source code from leaking. This is the belt-and-suspenders approach against the known `folders` bug. - **`excludeFiles` lists exact filenames** -- no globs. Context7 only indexes markdown by default, so there is no need to filter `*.ts`, `*.js`, `*.css` etc. (which would be invalid anyway). The five listed files are root-level markdown that would otherwise pollute the index with internal agent instructions and spec drafts. -- **`rules` is an array of 6 strings**, each under 200 characters, referencing actual filenames that exist in the repo. This replaces the previous plans' single-string approach (which would fail schema validation). The rules guide agents to start with `full-lean.md` and drill into trigger-specific files as needed. +- **`rules` is an array of 8 strings**, each under 200 characters, all in imperative mood. Context7 injects these verbatim into the LLM context alongside code snippets when `query-docs` is called — they are coding-agent guidelines, not file navigation hints. The previous plan's first three entries (`"Start with rules/full-lean.md..."`, `"For trigger-specific rules: click.md..."`, `"For integration patterns... use rules/integration.md"`) were navigation hints that misused the field: Context7 performs its own semantic search, so pointing an agent at a filename adds no value. The replacement rules surface the CRITICAL pitfalls documented in `rules/full-lean.md` and `rules/click.md`: the `overflow: clip` requirement for `viewProgress`, the `viewEnter` same-element re-trigger trap, hit-area flicker with hover/click, `pointerMove` jitter, and the accessibility requirements (`trigger: 'activate'`, `prefers-reduced-motion`, FOUC prevention). - **No `excludeFiles` globs** -- the previous detailed plan's `"*.ts"`, `"*.js"` entries would fail the schema's `^[^/\\]+$` pattern constraint. - **Dropped `packages/interact-debug`** from excludeFolders -- this directory does not exist. diff --git a/context7.json b/context7.json new file mode 100644 index 00000000..6be1215b --- /dev/null +++ b/context7.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "@wix/interact", + "description": "Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic.", + "folders": ["packages/interact/rules", "packages/interact/docs", "packages/interact"], + "excludeFolders": [ + "packages/interact/src", + "packages/interact/test", + "packages/motion", + "packages/motion-presets", + "apps", + ".github", + ".cursor", + ".claude", + "scripts", + "node_modules", + "dist" + ], + "excludeFiles": [ + "AGENTS.md", + "CLAUDE.md", + "CONTRIBUTING.md", + "readme-spec-1.md", + "readme-spec-2.md" + ], + "rules": [ + "Always call registerEffects() before Interact.create()", + "Use overflow: clip (not overflow: hidden) on all ancestors between source and scroll container for viewProgress", + "When viewEnter source and target are the same element, use type 'once' only — other types cause re-trigger loops", + "Separate source and target elements when hover or click effects change size or position to prevent hit-area flicker", + "Avoid same-element source/target with pointerMove hitArea:'self' and size-changing effects — causes jitter", + "Use trigger: 'activate' instead of 'click' to also handle keyboard activation (Enter/Space)", + "Call generate() from @wix/interact/web before page render for FOUC prevention with custom elements", + "Add prefers-reduced-motion conditions or set Interact.forceReducedMotion for accessibility" + ] +} From e4f9570a27d0cc2e56c9a120c0893b82e9e92ea5 Mon Sep 17 00:00:00 2001 From: ameerf-wix Date: Mon, 25 May 2026 14:16:54 +0300 Subject: [PATCH 4/4] context7.json + update plan --- .cursor/plans/context7_registration_91d783e5.plan.md | 4 +--- .yarnrc.yml | 2 +- context7.json | 4 +--- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/.cursor/plans/context7_registration_91d783e5.plan.md b/.cursor/plans/context7_registration_91d783e5.plan.md index a6e06dde..039adc16 100644 --- a/.cursor/plans/context7_registration_91d783e5.plan.md +++ b/.cursor/plans/context7_registration_91d783e5.plan.md @@ -106,9 +106,7 @@ New file at repo root: [context7.json](context7.json) "excludeFiles": [ "AGENTS.md", "CLAUDE.md", - "CONTRIBUTING.md", - "readme-spec-1.md", - "readme-spec-2.md" + "CONTRIBUTING.md" ], "rules": [ "Always call registerEffects() before Interact.create()", diff --git a/.yarnrc.yml b/.yarnrc.yml index d06c71c9..be098390 100644 --- a/.yarnrc.yml +++ b/.yarnrc.yml @@ -11,4 +11,4 @@ npmMinimalAgeGate: 14d npmPreapprovedPackages: - "@wix/*" -npmRegistryServer: "https://registry.npmjs.org/" +npmRegistryServer: "https://npm.dev.wixpress.com/" diff --git a/context7.json b/context7.json index 6be1215b..8478550a 100644 --- a/context7.json +++ b/context7.json @@ -19,9 +19,7 @@ "excludeFiles": [ "AGENTS.md", "CLAUDE.md", - "CONTRIBUTING.md", - "readme-spec-1.md", - "readme-spec-2.md" + "CONTRIBUTING.md" ], "rules": [ "Always call registerEffects() before Interact.create()",