nodality 1.2.1 → 1.2.2

package/README.md

@@ -1,183 +1,164 @@
-# Nodality
+<h1 align="center">Nodality</h1>
 
-This library works with elements represented as an array of HTML entities, and nodes that control the behavior of elements.  
-*Elements* is an array of objects. This array produces the code of elements you can use in your website.  
-*Nodes* is another array containing nodes that change the look and behavior of the generated elements.  
+<p align="center">
+  <strong>A user interface is two arrays: what exists, and what is done to it.</strong><br>
+  Both are plain data — so the pipeline that builds your page is inspectable,
+  diffable, and executable at build time <em>and</em> in the browser.
+</p>
 
-
-
-## Installation
-
-The easiest way to get up and running is to use **npm**:
-
-```bash
-npm create nodality@latest my-app
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/nodality"><img alt="npm" src="https://img.shields.io/npm/v/nodality?color=0f53a8"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-0f53a8">
+  <a href="https://github.com/nodalityjs/nodality/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/nodality?color=0f53a8"></a>
+  <a href="https://nodalityjs.github.io/"><img alt="docs" src="https://img.shields.io/badge/docs-nodalityjs.github.io-0f53a8"></a>
+</p>
 
 ---
 
-## Tutorial
-## Step 1
+## A whole navigation graph is one node
 
-Define an array of elements you want to display in your user interface:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nodalityjs/nodality/main/media/nodality-chain.gif"
+       alt="Three views transitioning into one another, each hop running a different shader effect" width="640">
+</p>
 
 ```js
-let elements = [
-  {
-    type: "h1",
-    text: "Hello"
-  }
-];
+{ op: "morph", effect: "t-vhs", duration: 620, back: true,
+  chain: [
+    { from: "home",   to: { Work: "work", Contact: "contact" } },
+    { from: "work",   to: { Aurora: "aurora" },  effect: "t-split" },
+    { from: "aurora", to: { Contact: "contact" }, effect: "t-bloom" },
+  ] }
 ```
 
----
+That is the entire source of the transitions above. The entries are
+**edges, not keyframes** — edge two is reachable *from* the state edge one
+lands on, so a landed view becomes a source in its turn. Settings on the
+node are defaults each edge may override, and `back` unwinds the path the
+user actually took rather than looking up an edge.
 
-## Step 2
+## Effects run on live DOM, and the DOM stays clickable
 
-Define an array of nodes that will adjust the behaviour of the element.  
-This particular node will add the **stroked text** effect:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nodalityjs/nodality/main/media/nodality-effect.gif"
+       alt="A warp effect following the pointer across a bar of links, then a link being clicked through it" width="640">
+</p>
 
 ```js
-let nodes = [
-  {
-    op: "blast"
-  }
+const nodes = [
+  { op: "flow",   target: ["bar"], by: "mouse", amount: 0.32 },
+  { op: "dither", target: ["bar"], levels: 10, size: 2, amount: 0.14 },
 ];
 ```
 
----
-
-## Step 3
+Two raster nodes aimed at one element compose into a **single** shader
+pass, in array order. The source is your live DOM, not an image you
+exported — and the links underneath still work: pointer input is inverted
+through the compiled transformation and re-dispatched, so a click lands
+where the user aimed rather than where the layout still thinks the link
+is. In the recording above, the pointer drives the warp and then clicks
+*through* it; the view that follows is the morph firing.
 
-Add the `nodes` array using the `.nodes()` modifier, and use the `.set()` method to mount the result of the code to the website.  
-Use the `code: true` option to also display the source code of the elements:
+## Install
 
-```js
-new Des()
-  .nodes(nodes)
-  .add(elements)
-  .set({
-    mount: "#mount",
-    code: true
-  });
+```bash
+npm create nodality@latest my-app
 ```
 
-Also define a `<div>` with `id="#mount"` that will serve as a root element to render the UI.
-
----
-
-## Everything Together
-
-Here is the complete working code which uses CDN for convenient testing.
+Or drop it into a page — no build step, no dependencies:
 
 ```html
-
-<!-- div for mounting the result -->
-<div id="#mount"></div>
+<div id="mount"></div>
 
 <script type="module">
-import {Des} from "https://www.unpkg.com/nodality@1.1.10/dist/index.esm.js";
-
-let elements = [
-  {
-    type: "h1",
-    text: "Hello"
-  }
-];
+import { Des } from "https://unpkg.com/nodality/dist/index.esm.js";
 
-let nodes = [
-  {
-    op: "blast"
-  }
+const elements = [
+  { id: "hero", type: "h1", text: "Hello" },
 ];
 
-new Des()
-  .nodes(nodes)
-  .add(elements)
-  .set({
-    mount: "#mount",
-    code: true
-  });
-</script>
-```
-
----
-
-## Result
-<img src="https://nodalityjs.github.io/assets/images/image-2601c982f747c8e3977a2d588f61e040.png">
-
-After running this code:
-
-- You will see an `<h1>` element on the screen.
-- When the user resizes the window and hits the **400–600px** breakpoint, a **stroke effect** will appear on the text, thanks to the `blast` modifier.
-- The **resulting code** of the UI will also be displayed below the rendered element.
-
----
-
-## Effects on live elements
-
-Nodes are not limited to design changes. A raster node compiles to a GPU
-shader pass over the element it targets, and several nodes aimed at one
-element compose into a **single** pass, in array order:
-
-```js
 const nodes = [
+  { op: { name: "gradient" }, target: ["hero"], colors: ["#1d6fe0", "#7fd1ff"] },
   { op: "dither", target: ["hero"], levels: 6, size: 2 },
-  { op: "flow",   target: ["hero"], by: "mouse" },
 ];
+
+new Des().nodes(nodes).add(elements).set({ mount: "#mount" });
+</script>
 ```
 
-The source is your live DOM, not an image you exported. Two capture
-backends sit underneath: a snapshot path that works in any WebGL browser,
-and an HTML-in-Canvas path that samples the running element directly
-where the browser supports it. The choice is automatic — if the newer API
-is absent the pipeline falls back rather than failing.
+`elements` says what exists. `nodes` says what is done to it. Nothing in
+`elements` names an effect and nothing in `nodes` names a component — the
+two meet only through `target`, so either can be written, stored or
+generated without the other.
 
-Effects do not cost you interaction. Pointer input is resolved through
-the inverse of the compiled transformation and re-dispatched, so links
-and buttons under an effect still work — including where the content is
-hosted inside the canvas and the browser's own hit testing cannot reach
-it.
+## What else it does
 
-## Transitions as data
+**Static site generation.** The same pair is interpreted at build time in
+a simulated DOM, so `npx nodality prerender` emits crawlable HTML that a
+consumer running no JavaScript can read, plus a sitemap, `hreflang`
+alternates and JSON-LD. The browser then re-reads the same pair and
+rebuilds on top — the pair is shipped, not consumed.
+[Docs →](https://nodalityjs.github.io/docs/ssg/prerender/)
 
-A `morph` node says which element becomes which, and on what interaction.
-There is no timeline to drive and no capture to manage:
+**Transitions and navigation graphs.** `{ op: "morph" }` in one hop or a
+whole chain, with per-edge effects, history-based `back`, and two capture
+backends chosen automatically.
+[Docs →](https://nodalityjs.github.io/docs/raster/morph/)
 
-```js
-const nodes = [
-  { op: "morph", from: "topnav",
-    to: { About: "about", Services: "offer", Contact: "contact" },
-    effect: "t-vhs", duration: 900, back: true },
-];
-```
+**Composable GPU effects.** Fifteen first-party raster ops, driveable by
+pointer, scroll or time, composed into one pass.
+[Docs →](https://nodalityjs.github.io/docs/raster/ops/)
 
-`from` and `to` name ids in your elements array; `back: true` wires the
-destination's own button to return. Mapping is by link label rather than
-position, because a responsive nav renders a different set of links per
-breakpoint.
+**An agent-operable surface, derived.** One node exposes your page to an
+AI agent as callable tools — traversing views, submitting a form you
+allowed, reading what is on screen — derived from the graph you already
+wrote rather than authored a second time, and also written into the
+prerendered HTML as a static manifest.
+[Docs →](https://nodalityjs.github.io/docs/raster/agent-surface/)
 
 ## For AI agents
 
-`nodality mcp` runs a Model Context Protocol server over stdio, so an
-agent can write interfaces against the real vocabulary instead of
-guessing at it:
+`nodality mcp` runs a Model Context Protocol server over stdio, so a
+generator writes against the real vocabulary instead of guessing at it:
 
 ```json
 { "mcpServers": { "nodality": { "command": "npx", "args": ["nodality", "mcp"] } } }
 ```
 
-Three tools: `list_ops` returns the op registry as data — every op with
-its stage, parameters, units, defaults; `validate_nodes` checks a node
+Three tools. `list_ops` returns the op registry as data — every op with
+its stage, parameters, units and defaults. `validate_nodes` checks a node
 array and returns a machine-readable report with did-you-mean
 suggestions, so `{ op: "dithr" }` comes back as `UNKNOWN_OP` suggesting
-`dither` rather than rendering nothing at all; `preview` renders an
-`(E, N)` pair to a self-contained HTML file. `preview` needs `jsdom` in
-your project (`npm i -D jsdom`) — it is required only for prerendering,
-so the library does not bundle it.
+`dither` rather than rendering nothing at all. `preview` renders an
+`(E, N)` pair to a self-contained HTML file (needs `jsdom` in your
+project; it is required only for prerendering, so the library does not
+bundle it).
 
-The same validator is available directly:
+The validator is available directly too:
 
 ```js
 import { validateNodes, describeOps } from "nodality/validate";
 ```
+
+## What this is not
+
+Nodality targets **static, content-shaped sites** — marketing pages,
+storefronts, documentation, brochure sites. It is not a replacement for a
+component framework with client-side state management, and it does not
+try to be one.
+
+Two honest caveats. The HTML-in-Canvas capture backend is **experimental
+and flag-gated**: where it is unavailable the pipeline falls back to
+snapshot capture on its own, so a page authored against it degrades to
+stills rather than breaking. And determinism is a property of the
+compiled artefact — the same pair always produces the same output — not
+of the pixels a particular GPU eventually paints.
+
+## Links
+
+- **Docs** — [nodalityjs.github.io](https://nodalityjs.github.io/)
+- **Live demos** — [a navigation graph](http://www.gesos.cz/chain-demo.html) · [a morph in production](http://www.gesos.cz/morph.html)
+- **Built with it** — [blue70.cz](https://www.blue70.cz) · [sls3.cz](https://www.sls3.cz) · [gesos.cz](http://www.gesos.cz) · [relays.app](https://relays.app)
+- **Releases** — [changelog and release notes](https://github.com/nodalityjs/nodality/releases)
+
+MIT © Filip Vabroušek

package/dist/animator.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/animator.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/audionew.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/audionew.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/base.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/base.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-desktop-bar.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-desktop-bar.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-mobile-bar.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-mobile-bar.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.0
+ * nodality v1.2.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */