\n\n\n\n\n\n```\n\nThat script tag is enough. When the module loads, VSN finds the\n`script[type=\"text/vsn\"]` blocks, registers their behaviors, and mounts the\ndocument body. The repository's examples use this same pattern.\n\nIf the built file is served from another location, change the `src` path to\nmatch it.\n\n## How the example works\n\nThe CFS block selects `#counter`, so that element becomes the behavior root.\nIts declarations (`count` and `active`) are reactive state in that root's\nscope. Descendants inherit the scope.\n\n- `vsn-bind:from=\"count\"` writes scope state into the element.\n- `vsn-on:click=\"...\"` runs CFS when the button is clicked.\n- `vsn-show=\"active\"` toggles the element's native `hidden` state while\n keeping it mounted.\n- Assigning `count` or `active` automatically updates every dependent binding.\n\n`script[type=\"text/vsn\"]` contains CFS, not JavaScript. CFS uses CSS-like\nselectors for behavior roots and a small JavaScript-like language for state,\nfunctions, expressions, and control flow.\n\n## CFS behaviors\n\nA behavior can contain state declarations, lifecycle blocks, functions, event\nhandlers, and nested selectors:\n\n```html\n\n \n
\n Dialog content\n
\n\n\n\n```\n\nNested selectors match descendants. Use `&` when the nested selector should\nreplace the parent selector, for example `&.active`.\n\nUseful CFS constructs include:\n\n```cfs\nuse fetch as request;\n\n.profile {\n name: \"Ada\";\n saved: false;\n\n save() {\n saved = true;\n }\n\n async load() {\n response = await request(\"/api/profile\");\n name = await response.text();\n }\n\n on keyup!escape() {\n saved = false;\n }\n}\n```\n\nNamed functions are synchronous unless declared `async`. Async functions can\nuse `await` and return promises. State can contain plain objects and arrays;\nnested mutations are observable as well as assignments to a whole value.\n\n### Directives in CFS\n\nDirectives connect state to DOM attributes, properties, and styles:\n\n```cfs\n@aria-label :< label; // scope -> attribute\n@data-id :> id; // attribute -> scope\n@value := name; // two-way form binding\n@class :< { selected: active }; // reactive class map\n$display :< (visible ? \"block\" : \"none\"); // reactive style\n```\n\nThe direction operators mean:\n\n| Operator | Direction |\n| --- | --- |\n| `:<` | scope to element |\n| `:>` | element to scope |\n| `:=` | two-way |\n\n`self`, `parent`, and `root` refer to the current, parent, and behavior-root\nscopes. `!as(name)` gives a behavior a stable scope alias. A nested behavior\ncan use `!group(\"name\")` to expose its live instances as a collection on the\nparent behavior.\n\n## HTML directives\n\nFor simple behavior, keep the logic in the markup and use inline `vsn-*`\nattributes:\n\n| Attribute | What it does |\n| --- | --- |\n| `vsn-bind=\"name\"` | Automatic binding; use an explicit direction when ownership matters. |\n| `vsn-bind:from=\"name\"` | Writes scope state to a display element or control. |\n| `vsn-bind:to=\"name\"` | Reads an element or control into scope state. |\n| `vsn-text=\"message\"` | Writes text with `textContent`. |\n| `vsn-html=\"markup\"` | Writes HTML through the configured sanitizer. |\n| `vsn-if=\"visible\"` | Mounts and unmounts the element as the condition changes. |\n| `vsn-show=\"visible\"` | Toggles `hidden` without unmounting the element. |\n| `vsn-on:event=\"...\"` | Runs CFS in response to a DOM event. |\n| `vsn-construct=\"...\"` | Runs CFS when the element binds. |\n| `vsn-destruct=\"...\"` | Runs CFS when the element unbinds. |\n| `vsn-each=\"items as item, index\"` | Repeats a `` for an array. |\n| `vsn-get=\"/url\"` | Fetches a response and optionally swaps it into the page. |\n\nFor form controls, an unqualified `vsn-bind` is two-way. On display elements,\nthe unqualified form can seed state from existing text during normal mounting\nor hydration. Prefer `:from`, `:to`, and `:=` when the direction should be\nobvious to a reader.\n\nEvent flags can be added after `!`:\n\n```html\n\n\n\n\n```\n\nBuilt-in flags include `prevent`, `stop`, `self`, `outside`, `once`,\n`passive`, `capture`, `debounce`, modifier keys, keyboard keys such as\n`enter` and `escape`, and viewport flags such as `minwidth` and `maxwidth`.\n\n## Lists and conditional UI\n\nRepeat a template with `vsn-each`. A unique `vsn-key` preserves row identity,\nfocus, form values, animations, and child behaviors when the array is reordered\nor updated:\n\n```html\n
\n \n
\n \n #\n
\n \n
\n```\n\n`vsn-if` really mounts and unmounts its element, so `construct`, `destruct`,\nand event cleanup run for each lifecycle. `vsn-show` leaves the element in the\nDOM and toggles `hidden`.\n\nTransitions are opt-in. In this example the containing behavior owns\n`open`, `entered`, and `leaving`:\n\n```html\n\n \n\n \n Panel\n \n\n\n\n```\n\n```css\n.fade-enter,\n.fade-leave-to {\n opacity: 0;\n}\n\n.fade-enter-active,\n.fade-leave-active {\n transition: opacity 150ms ease;\n}\n```\n\n## Requests and partial HTML\n\n`vsn-get` is a request trigger and an HTML swap primitive. It supports forms,\nmethods, request bodies, headers, loading/error/data state, history, focus\nrestoration, and cancellation:\n\n```html\n\n \n \n \n \n\n
Loading…
\n \n
Results appear here.
\n\n\n\n```\n\nResponses are sanitized by default. A non-2xx response does not swap HTML and\ndispatches `vsn:getError`. Add `!trusted` only for a response that is under\nthe application's control:\n\n```html\n\n Load fragment\n\n```\n\nTrusted fragments may contain VSN behavior scripts and are processed by the\nengine. Untrusted fragments do not activate scripts or `vsn-*` attributes.\n\n## Server-rendered pages\n\nThe auto-mounted module enhances the existing document in place. Keep the\ninitial text, form values, and semantic HTML in the server response; VSN then\nconnects those elements to reactive state and behavior.\n\n## Plugins\n\nPlugins are opt-in. Load their browser modules before the core module:\n\n```html\n\n\n\n\n```\n\nThe templates plugin adds the `html` tagged template for composing HTML in\nCFS. The sanitize plugin replaces the default sanitizer with a configured\nsanitizer (including DOMPurify when available). The microdata plugin adds the\n`!microdata` behavior modifier and the `microdata()` helper.\n\n## Behavior libraries\n\nReusable behavior packages should opt in through a namespaced class, keep one\nCFS behavior per module, and document the markup contract around it:\n\n```html\n\n \n
Content
\n\n\n\n```\n\nThe `vsn-` prefix is reserved for first-party behaviors. Independent packages\nshould use their own stable prefix, such as `.acme-dialog`. See the\n[behavior contract](./behaviors/CONTRACT.md) for the required markup, state,\nevent, accessibility, and cleanup documentation.\n\n## Examples and development\n\nThe [examples](./examples/) directory is a runnable cookbook covering\nbindings, forms, lists, requests, templates, lifecycle, accessibility, and\nmore. Its [README](./examples/README.md) maps each example to the feature it\ndemonstrates.\n\n```bash\nnpm run build # build ESM, CommonJS, browser, plugin, and type outputs\nnpm test # run the test suite\nnpm run typecheck # type-check source and tests\n```\n\nFor CFS syntax, remember that hyphenated identifiers are supported. To\nsubtract numbers, put whitespace around the operator: use `count - 1`, not\n`count-1`.\n","readmeFilename":"README.md"}