feat: add @tanstack/marko-store - a Marko v6 adapter for TanStack Store

.changeset/add-marko-store.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/marko-store": minor
+---
+
+Add `@tanstack/marko-store`, a Marko 6 adapter for TanStack Store. It provides the `<store-selector>` and `<store-atom>` tags — the Marko equivalents of the `useSelector` / `useStore` adapters — and re-exports the full `@tanstack/store` core.

.gitignore

@@ -56,3 +56,6 @@ examples/angular/store-context/.angular/cache/21.2.7/store-context/angular-compi
 examples/angular/stores/.angular/cache/21.2.7/stores/.tsbuildinfo
 examples/angular/stores/.angular/cache/21.2.7/stores/angular-compiler.db
 examples/angular/stores/.angular/cache/21.2.7/stores/angular-compiler.db-lock
+test-results/
+*.tsbuildinfo
+packages/marko-store/e2e/pw-results.json

.prettierrc

@@ -2,6 +2,6 @@
   "semi": false,
   "singleQuote": true,
   "trailingComma": "all",
-  "plugins": ["prettier-plugin-svelte"],
+  "plugins": ["prettier-plugin-svelte", "prettier-plugin-marko"],
   "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
 }

docs/config.json

@@ -85,6 +85,15 @@
               "to": "framework/lit/quick-start"
             }
           ]
+        },
+        {
+          "label": "marko",
+          "children": [
+            {
+              "label": "Quick Start - Marko",
+              "to": "framework/marko/quick-start"
+            }
+          ]
         }
       ]
     },
@@ -159,6 +168,12 @@
               "to": "framework/lit/reference/index"
             }
           ]
+        },
+        {
+          "label": "marko",
+          "children": [
+            { "label": "Marko Tags", "to": "framework/marko/reference/index" }
+          ]
         }
       ]
     },
@@ -507,6 +522,16 @@
               "to": "framework/lit/reference/interfaces/UseSelectorOptions"
             }
           ]
+        },
+        {
+          "label": "marko",
+          "children": [
+            { "label": "<store-provider>", "to": "framework/marko/reference/tags/store-provider" },
+            { "label": "<store-context>", "to": "framework/marko/reference/tags/store-context" },
+            { "label": "<store-selector>", "to": "framework/marko/reference/tags/store-selector" },
+            { "label": "<store-atom>", "to": "framework/marko/reference/tags/store-atom" },
+            { "label": "<stream-store-provider>", "to": "framework/marko/reference/tags/stream-store-provider" }
+          ]
         }
       ]
     },
@@ -672,6 +697,16 @@
               "to": "framework/lit/examples/simple"
             }
           ]
+        },
+        {
+          "label": "marko",
+          "children": [
+            { "label": "Simple", "to": "framework/marko/examples/simple" },
+            { "label": "Atoms", "to": "framework/marko/examples/atoms" },
+            { "label": "Stores", "to": "framework/marko/examples/stores" },
+            { "label": "Store Actions", "to": "framework/marko/examples/store-actions" },
+            { "label": "Store Context", "to": "framework/marko/examples/store-context" }
+          ]
         }
       ]
     }

docs/framework/marko/quick-start.md

@@ -0,0 +1,88 @@
+---
+title: Quick Start
+id: quick-start
+---
+
+The basic Marko app example to get started with TanStack `marko-store`.
+
+Marko exposes the store through tags rather than hooks. `<store-selector>` reads a slice of a store and keeps it live, re-rendering only when that selected slice changes. State is updated with `store.setState`, exactly as in the other adapters.
+
+```marko
+import { createStore } from '@tanstack/marko-store'
+
+// You can instantiate a Store outside of Marko templates too!
+export const store = createStore({
+  dogs: 0,
+  cats: 0,
+})
+
+<div>
+  <h1>How many of your friends like cats or dogs?</h1>
+  <p>
+    Press one of the buttons to add a counter of how many of your friends
+    like cats or dogs.
+  </p>
+
+  <button onClick() { store.setState((s) => ({ ...s, dogs: s.dogs + 1 })) }>
+    My Friend Likes dogs
+  </button>
+  // <store-selector> subscribes only to state.dogs
+  <store-selector/dogs from=() => store selector=(state) => state.dogs/>
+  <div>dogs: ${dogs}</div>
+
+  <button onClick() { store.setState((s) => ({ ...s, cats: s.cats + 1 })) }>
+    My Friend Likes cats
+  </button>
+  <store-selector/cats from=() => store selector=(state) => state.cats/>
+  <div>cats: ${cats}</div>
+</div>
+```
+
+`<store-selector>` binds the latest selected value to its tag variable (here `dogs` and `cats`) and only updates when that specific selection changes.
+
+## A writable value: `<store-atom>`
+
+For a single writable value, `<store-atom>` gives two-way access to an atom — read its tag variable, and assign to it to write back:
+
+```marko
+import { createAtom } from '@tanstack/marko-store'
+export const countAtom = createAtom(0)
+
+<store-atom/count from=() => countAtom/>
+<button onClick() { count++ }>count is ${count}</button>
+```
+
+## Sharing stores without imports: `<store-provider>` and `<store-context>`
+
+To distribute one or more stores down the tree without importing them everywhere, wrap a subtree in `<store-provider>` with a bundle of stores, read any value below with `<store-selector>` in context mode, and grab the bundle to write with `<store-context>`:
+
+```marko
+import { createStore } from '@tanstack/marko-store'
+
+<store-provider value=() => ({ cats: createStore({ count: 0 }) })>
+  <store-selector/catCount context=(c) => c.cats selector=(s) => s.count/>
+  <div>cats: ${catCount}</div>
+
+  <store-context/ctx/>
+  <button onClick() { ctx().cats.setState((s) => ({ count: s.count + 1 })) }>add a cat</button>
+</store-provider>
+```
+
+## Server rendering and streaming
+
+`marko-store` is resumable: a store rendered on the server stays live on the client after resume, with no re-execution. For server-computed, per-request data that arrives mid-render through `<await>`, create the store from the awaited value inside the await using `<stream-store-provider>`. The value then renders on the server with no first-paint flash and the store stays live after resume:
+
+```marko
+import { createStore } from '@tanstack/marko-store'
+
+<await|user|=fetchUser()>
+  <stream-store-provider key='user' value=() => ({ user: createStore(user) })>
+    <store-selector/name key='user' context=(c) => c.user selector=(s) => s.name/>
+    <div>${name}</div>
+  </stream-store-provider>
+</await>
+```
+
+Use a plain `<await>` for in-order streaming, or wrap it in `<try>` with a `<@placeholder>` for out-of-order streaming. Each `<stream-store-provider>` needs a distinct `key`.
+
+For production SSR, use [`@marko/run`](https://github.com/marko-js/run), Marko's official server framework. Standalone `@marko/vite` SSR is intended for development only.

docs/framework/marko/reference/index.md

@@ -0,0 +1,20 @@
+---
+id: "@tanstack/marko-store"
+title: "@tanstack/marko-store"
+---
+
+# @tanstack/marko-store
+
+The Marko adapter exposes its API as custom tags. Each tag is documented on its own page below.
+
+## Tags
+
+- [`<store-provider>`](tags/store-provider.md)
+- [`<store-context>`](tags/store-context.md)
+- [`<store-selector>`](tags/store-selector.md)
+- [`<store-atom>`](tags/store-atom.md)
+- [`<stream-store-provider>`](tags/stream-store-provider.md)
+
+## Re-exports
+
+`@tanstack/marko-store` re-exports the full `@tanstack/store` core, including `createStore`, `createAtom`, `Store`, `Derived`, and `shallow`. These are framework-agnostic; see the Store API Reference for their documentation.

docs/framework/marko/reference/tags/store-atom.md

@@ -0,0 +1,29 @@
+---
+id: store-atom
+title: "<store-atom>"
+---
+
+# Tag: `<store-atom>`
+
+Binds a single writable atom from `createAtom()` as a two-way value: it reads the atom's current value and writes back through the atom's `set`. Use it for a standalone writable value; for a `Store` (from `createStore`), read it with `<store-selector>` instead.
+
+```marko
+<store-atom/qty from=() => qtyAtom>
+<p>Quantity: ${qty}</p>
+```
+
+## Type parameters
+
+- **`T`** — the atom's value type.
+
+## Attributes
+
+- **`from`** — `() => { get(); set(); subscribe() }` (required). A thunk returning the atom (from `createAtom()`). The atom must have a `set` method; a `Store` does not and will throw.
+
+## Tag variable
+
+The atom's current value, typed `T`. The tag exposes a `value`/`valueChange` pair, so it is two-way bindable — bind it to a variable with `value:=` and assignments write back through the atom's `set`.
+
+## Behavior
+
+The value is seeded from `from().get()` at render and kept live by a subscription on mount, so it updates whenever the atom changes from anywhere. Writes go through `from().set(next)`. If `from()` returns something without a `set` method (such as a `Store`), the tag throws with guidance to use `<store-selector>`.

docs/framework/marko/reference/tags/store-context.md

@@ -0,0 +1,28 @@
+---
+id: store-context
+title: "<store-context>"
+---
+
+# Tag: `<store-context>`
+
+Reads the store bundle provided by the nearest `<store-provider>` with a matching key, so a descendant can use the live stores directly (for example to dispatch actions). Binds a getter.
+
+```marko
+<store-context/getBundle>
+<const/cart=getBundle().cart>
+<button onClick() { cart.setState((s) => ({ count: s.count + 1 })) }>
+  Add one
+</button>
+```
+
+## Attributes
+
+- **`key`** — `string` (optional, default `"__tanstack_store_context"`). The context key to read. Must match the key the `<store-provider>` used.
+
+## Tag variable
+
+A getter function, `() => bundle`. Call it to read the current bundle parked by the provider. It is a thunk rather than the bundle itself so the read happens at call time, after the provider has parked the bundle.
+
+## Behavior
+
+At render the tag checks that a bundle exists on `$global` under the key and throws if none is found — that is, when there is no `<store-provider>` above it. It does not subscribe to anything; use `<store-selector>` when you need a value that re-renders on change.

docs/framework/marko/reference/tags/store-provider.md

@@ -0,0 +1,28 @@
+---
+id: store-provider
+title: "<store-provider>"
+---
+
+# Tag: `<store-provider>`
+
+Creates a bundle of stores for the current request and makes it available to descendant tags by a context key. Wraps the content it is given.
+
+```marko
+<store-provider value=() => ({ cart: createStore({ items: [] }) })>
+  <cart-view/>
+</store-provider>
+```
+
+## Attributes
+
+- **`value`** — `() => Record<string, unknown>` (required). A thunk returning the bundle of named stores or atoms to provide. It is called once on the server at render and again on the client at mount, so each environment gets its own live instances.
+- **`key`** — `string` (optional, default `"__tanstack_store_context"`). The context key the bundle is parked under. Use distinct keys to provide more than one bundle on a page. The matching `<store-context>` and context-mode `<store-selector>` must use the same key.
+- **`content`** — `Marko.Body` (optional). The body rendered inside the provider, usually supplied implicitly as the tag's children.
+
+## Tag variable
+
+None. `<store-provider>` is a wrapper: it renders its content and binds no tag variable.
+
+## Behavior
+
+The bundle is parked on `$global` under the context key at render, and re-created and published on mount so client subscribers attach to live instances. Only one provider may claim a given key: a second `<store-provider>` (or a `<stream-store-provider>`) on the same key throws, to prevent two writers silently clobbering the same box. On destroy the box and its owner marker are cleared.

docs/framework/marko/reference/tags/store-selector.md

@@ -0,0 +1,38 @@
+---
+id: store-selector
+title: "<store-selector>"
+---
+
+# Tag: `<store-selector>`
+
+Subscribes to a store or atom, projects a slice of it, and re-renders when that slice changes. Works in two modes: `from` (a store passed directly) or `context` (a member of the provided bundle). Binds the selected value.
+
+```marko
+<!-- from mode -->
+<store-selector/count from=() => cartStore selector=(s) => s.items.length>
+<p>${count} items</p>
+
+<!-- context mode -->
+<store-selector/count context=(b) => b.cart selector=(s) => s.items.length>
+```
+
+## Type parameters
+
+- **`TSource`** — the snapshot type of the source store or atom.
+- **`TSelected`** — the projected slice type. Defaults to `TSource` when no `selector` is given.
+
+## Attributes
+
+- **`from`** — `() => { get(); subscribe() }` (optional). A thunk returning the source store or atom directly. Mutually exclusive with `context`.
+- **`context`** — `(bundle) => { get(); subscribe() }` (optional). Selects the source from the provided bundle. Mutually exclusive with `from`. Annotate the parameter in typed projects, e.g. `context=(b: any) => b.cart`.
+- **`key`** — `string` (optional, default `"__tanstack_store_context"`). The context key to read in `context` mode. Must match the provider's key.
+- **`selector`** — `(snapshot: TSource) => TSelected` (optional, default identity). Projects the slice to track.
+- **`compare`** — `(a: TSelected, b: TSelected) => boolean` (optional, default `===`). Equality check used to drop redundant updates.
+
+## Tag variable
+
+The current selected value, typed `TSelected | undefined`. It is `undefined` only at the brief moment on resume before a context-mode provider has parked its bundle; the tag recovers automatically and updates once the bundle is available.
+
+## Behavior
+
+Passing both `from` and `context` throws. The value is seeded at render (null-tolerant in context mode), then kept live by a subscription established on mount. In context mode the tag also listens on the internal publish bus, so it attaches to the store the moment the provider parks it during streaming or resume. Changing the source or swapping the `selector` re-projects; `compare` gates only store mutations, never a deliberate selector change.

docs/framework/marko/reference/tags/stream-store-provider.md

@@ -0,0 +1,31 @@
+---
+id: stream-store-provider
+title: "<stream-store-provider>"
+---
+
+# Tag: `<stream-store-provider>`
+
+A provider for progressive streaming: it creates a per-request store bundle from data that becomes available inside a late `<await>`, and keeps it live across the server-to-client boundary. Place it inside the awaited body so the awaited value is captured into `value`. Wraps its content.
+
+```marko
+<await|order|=loadOrder(orderId)>
+  <stream-store-provider key="order" value=() => ({ order: createStore(order) })>
+    <store-selector/total context=(b) => b.order selector=(o) => o.total>
+    <p>Total: ${total}</p>
+  </stream-store-provider>
+</await>
+```
+
+## Attributes
+
+- **`value`** — `() => Record<string, unknown>` (required). A thunk returning the bundle of stores or atoms, built from the awaited per-request data. Called on the server at render and again on the client at mount.
+- **`key`** — `string` (**required**). The context key the bundle is parked under. Unlike `<store-provider>`, there is no default; each streamed provider needs an explicit, distinct key.
+- **`content`** — `Marko.Body` (optional). The body rendered inside the provider.
+
+## Tag variable
+
+None. Like `<store-provider>`, it renders its content and binds no tag variable.
+
+## Behavior
+
+This is the "born-with-data" transport. The awaited value is captured by `value` and crosses to the client through the await subtree's resume scope; the bundle is built into `$global` under the key on the server, and rebuilt and published on mount so client subscribers attach to live instances. It shares `<store-provider>`'s owner marker, so a `<store-provider>` and a `<stream-store-provider>` on the same key detect each other and throw rather than clobber. For production, a streaming Marko app must run under `@marko/run`; a standalone `@marko/vite` production build does not coordinate resume correctly.

examples/marko/README.md

@@ -0,0 +1,25 @@
+# Marko examples for TanStack Store
+
+These mirror the sibling adapter examples (react, svelte, …) using
+`@tanstack/marko-store`.
+
+Five client-only parity examples — `stores`, `simple`, `atoms`, `store-actions`,
+`store-context` — match the scenarios the other frameworks ship. Each is a
+browser-only SPA: `vite.config.ts` uses `marko({ linked: false })` (Marko + Vite
+is SSR-first, so a client-only build needs `linked: false`), and `src/index.ts`
+mounts the app.
+
+Three Marko-specific SSR examples — `ssr-resume`, `ssr-per-request-multi`,
+`streaming` — show server render + resume, per-request data rebuilt on the
+client, and streaming a store into a late `<await>` (born-with-data, in-order and
+out-of-order). Each runs a small Marko Vite dev server (`node server.mjs`); open
+the routes named in its README.
+
+Those three SSR servers are development demonstrations, not deployable production
+servers. Real Marko production uses `@marko/run`; a dedicated `@marko/run`
+example will be added separately.
+
+In this monorepo you do not install per example. Add `examples/marko/**` to
+`pnpm-workspace.yaml`, run `pnpm install` once at the root, then start an example
+by folder (`cd examples/marko/<name> && pnpm dev`) or by name
+(`pnpm --filter @tanstack/store-example-marko-<name> dev`).

examples/marko/atoms/README.md

@@ -0,0 +1,10 @@
+# Marko Store — atoms
+
+A module-level `createAtom`. The read-only total uses `<store-selector>` (no
+selector function = the whole value); the editable count uses `<store-atom>`,
+whose binding writes back through `atom.set`. Reset calls `atom.set(0)`.
+
+To run this example:
+
+- `npm install`
+- `npm run dev`