seitu 0.15.0 → 0.16.0

package/skills/README.md

@@ -0,0 +1,114 @@
+# Seitu agent skills (TanStack Intent)
+
+These skills teach AI assistants how to integrate [Seitu](https://seitu.letstri.dev) in **your** app — not how to work on the Seitu library monorepo.
+
+Skills ship inside the `seitu` npm package and are versioned with each release. They include `sources` metadata pointing at docs and source files so maintainers can detect drift when documentation changes.
+
+## Install via npm (recommended)
+
+After adding Seitu to your project:
+
+```bash
+pnpm add seitu
+pnpm dlx @tanstack/intent@latest install
+```
+
+Intent discovers `seitu` in `node_modules`, reads the skills bundled with your installed version, and writes lightweight skill-loading guidance into your agent config (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, etc.).
+
+List or load a specific skill:
+
+```bash
+pnpm dlx @tanstack/intent@latest list
+pnpm dlx @tanstack/intent@latest load seitu#create-store
+```
+
+When you `pnpm update seitu`, skills update with the package — knowledge travels through npm, not model training cutoffs.
+
+Start with **`seitu-overview`** — module map, mental model, and decision tree.
+
+## Manual install (Cursor)
+
+Copy skill folders into `.cursor/skills/`:
+
+```bash
+cp -r node_modules/seitu/skills/seitu-overview .cursor/skills/
+cp -r node_modules/seitu/skills/create-store .cursor/skills/
+```
+
+Restart Cursor or start a new agent chat so skills are picked up.
+
+## Skills
+
+### Core (`seitu`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [seitu-overview](./seitu-overview/SKILL.md) | `seitu#seitu-overview` | Read first — module map and primitive selection |
+| [create-store](./create-store/SKILL.md) | `seitu#create-store` | Simple in-memory reactive state |
+| [create-schema-store](./create-schema-store/SKILL.md) | `seitu#create-schema-store` | Schema-validated state (Zod, Valibot, ArkType) |
+| [create-computed](./create-computed/SKILL.md) | `seitu#create-computed` | Derived read-only values |
+| [create-debounced](./create-debounced/SKILL.md) | `seitu#create-debounced` | Debounce subscribable updates |
+| [create-throttled](./create-throttled/SKILL.md) | `seitu#create-throttled` | Throttle subscribable updates |
+| [create-debounced-fn](./create-debounced-fn/SKILL.md) | `seitu#create-debounced-fn` | Debounced function with reactive result |
+| [create-throttled-fn](./create-throttled-fn/SKILL.md) | `seitu#create-throttled-fn` | Throttled function with reactive result |
+| [create-subscription](./create-subscription/SKILL.md) | `seitu#create-subscription` | Low-level subscribe/notify |
+| [create-readable-subscription](./create-readable-subscription/SKILL.md) | `seitu#create-readable-subscription` | Compose standard Readable & Subscribable |
+
+### Web (`seitu/web`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [create-web-storage-value](./create-web-storage-value/SKILL.md) | `seitu#create-web-storage-value` | Single-key localStorage / sessionStorage |
+| [create-web-storage](./create-web-storage/SKILL.md) | `seitu#create-web-storage` | Multi-key web storage |
+| [create-indexed-db-storage](./create-indexed-db-storage/SKILL.md) | `seitu#create-indexed-db-storage` | Large or async IndexedDB state |
+| [create-media-query](./create-media-query/SKILL.md) | `seitu#create-media-query` | Reactive CSS media queries |
+| [create-is-online](./create-is-online/SKILL.md) | `seitu#create-is-online` | Online / offline status |
+| [create-scroll-state](./create-scroll-state/SKILL.md) | `seitu#create-scroll-state` | Scroll position and edges |
+
+### React (`seitu/react`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [use-subscription-react](./use-subscription-react/SKILL.md) | `seitu#use-subscription-react` | Hook for any Seitu primitive |
+| [subscription-react](./subscription-react/SKILL.md) | `seitu#subscription-react` | Render-prop component |
+
+### Vue (`seitu/vue`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [use-subscription-vue](./use-subscription-vue/SKILL.md) | `seitu#use-subscription-vue` | Composable for any Seitu primitive |
+
+### Solid (`seitu/solid`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [use-subscription-solid](./use-subscription-solid/SKILL.md) | `seitu#use-subscription-solid` | Primitive returning an accessor for any Seitu primitive |
+| [subscription-solid](./subscription-solid/SKILL.md) | `seitu#subscription-solid` | Render-prop component |
+
+### Svelte (`seitu/svelte`)
+
+| Skill | Intent id | When to use |
+|-------|-----------|-------------|
+| [use-subscription-svelte](./use-subscription-svelte/SKILL.md) | `seitu#use-subscription-svelte` | Binding returning a Svelte `Readable` store for any Seitu primitive |
+
+## Registry and version history
+
+The package includes the `tanstack-intent` npm keyword. Published versions are indexed on the [Agent Skills Registry](https://tanstack.com/intent/registry) with skill history per release.
+
+## Without skills
+
+- Official docs: https://seitu.letstri.dev/docs
+- LLM-oriented export: https://seitu.letstri.dev/llms.txt
+
+## Maintainer workflow (this repo)
+
+From `seitu/`:
+
+```bash
+pnpm run skills:validate   # structure + packaging before publish
+pnpm run skills:stale      # flag drift vs docs/sources
+pnpm run skills:sync-state # refresh source SHAs after doc/source edits
+pnpm run skills:upgrade    # re-apply frontmatter + Common Mistakes from _artifacts
+```
+
+CI runs `intent validate` on PRs and `intent stale` after releases (`.github/workflows/check-skills.yml`). Update `library_version` in SKILL frontmatter when cutting a release.

package/skills/create-computed/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: create-computed
+description: >-
+  Derived read-only subscription from one or many sources.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/core/computed.mdx
+  - letstri/seitu:seitu/src/core/computed.ts
+---
+
+# createComputed
+
+Derived read-only subscription from one or many sources. Lazy — only subscribes to sources when it has its own subscribers.
+
+## Single source
+
+```ts
+import { createComputed, createStore } from 'seitu'
+
+const store = createStore({ a: 1, b: 2 })
+const sum = createComputed(store, s => s.a + s.b)
+sum.get() // 3
+```
+
+## Multiple sources
+
+```ts
+import { createComputed, createStore } from 'seitu'
+
+const a = createStore(1)
+const b = createStore(2)
+const total = createComputed([a, b], ([a, b]) => a + b)
+total.get() // 3
+```
+
+## Overloads
+
+```ts
+function createComputed<T, R>(source: Source<T>, transform: (value: T) => R): Computed<R>
+function createComputed<S extends Source[], R>(sources: [...S], transform: (values: SourceValues<S>) => R): Computed<R>
+```
+
+## Interface
+
+```ts
+interface Computed<T> extends Readable<T>, Subscribable<T> {}
+```
+
+Read-only. No `set()`.
+## Common Mistakes
+
+### [HIGH] Recomputing manually in components
+
+Wrong:
+
+```ts
+const sum = a.get() + b.get()
+```
+
+Correct:
+
+```ts
+const sum = createComputed([a, b], ([x, y]) => x + y)
+```
+
+createComputed subscribes to sources and caches until they notify.
+
+### [HIGH] Creating computed inside render
+
+Wrong:
+
+```ts
+function App() {
+  const total = createComputed(store, s => s.a + s.b)
+}
+```
+
+Correct:
+
+```ts
+const total = createComputed(store, s => s.a + s.b)
+```
+
+New computed each render re-subscribes and loses memoization benefits.
+
+### [MEDIUM] Writing to computed
+
+Wrong:
+
+```ts
+sum.set(10)
+```
+
+Correct:
+
+```ts
+store.set({ a: 5, b: 5 })
+```
+
+Computed is read-only; use the source store's set().
+
+## Source
+
+`src/core/computed.ts`

package/skills/create-debounced/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: create-debounced
+description: >-
+  Debounce updates from a source subscribable.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/core/debounced.mdx
+  - letstri/seitu:seitu/src/core/debounced.ts
+---
+
+# createDebounced
+
+Wraps a source subscribable with debounce. Emits the latest value after `wait` ms of inactivity.
+
+```ts
+import { createStore, createDebounced } from 'seitu'
+
+const input = createStore('')
+const debounced = createDebounced(input, 300)
+debounced.subscribe(value => console.log('debounced:', value))
+debounced.get() // current debounced value
+```
+
+## Signature
+
+```ts
+function createDebounced<T>(source: Readable<T> & Subscribable<T>, wait: number): Debounced<T>
+```
+
+## Interface
+
+```ts
+interface Debounced<T> extends Readable<T>, Subscribable<T> {}
+```
+
+Read-only. Lazy subscription — only subscribes to source when it has its own subscribers.
+## Common Mistakes
+
+### [HIGH] Debouncing the source instead of wrapping it
+
+Wrong:
+
+```ts
+const raw = createStore(0)
+setTimeout(() => raw.set(v), 300)
+```
+
+Correct:
+
+```ts
+const debounced = createDebounced(raw, 300)
+```
+
+createDebounced wraps a Readable & Subscribable; mutating the source bypasses debounce.
+
+### [MEDIUM] Expecting immediate get after source change
+
+Wrong:
+
+```ts
+source.set(1); debounced.get() // expects 1 immediately
+```
+
+Correct:
+
+```ts
+debounced.subscribe(v => console.log(v))
+```
+
+get() returns last emitted value until wait elapses.
+
+### [LOW] Zero or negative wait
+
+Wrong:
+
+```ts
+createDebounced(source, 0)
+```
+
+Correct:
+
+```ts
+createDebounced(source, 300)
+```
+
+Invalid wait breaks timing expectations.
+
+## Source
+
+`src/core/debounced.ts`

package/skills/create-debounced-fn/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: create-debounced-fn
+description: >-
+  Debounced callable with reactive return value.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/core/debounced-fn.mdx
+  - letstri/seitu:seitu/src/core/debounced-fn.ts
+---
+
+# createDebouncedFn
+
+Wraps a plain function. The return value becomes subscribable state. Each call resets the debounce timer.
+
+```ts
+import { createDebouncedFn } from 'seitu'
+
+const search = createDebouncedFn((q: string) => fetch(`/api?q=${q}`), 300)
+search('hello') // debounced — fires after 300ms of inactivity
+search.get() // latest return value (undefined until first call)
+search.subscribe(result => console.log('result:', result))
+```
+
+## Signature
+
+```ts
+function createDebouncedFn<F extends (...args: any[]) => any>(fn: F, wait: number): DebouncedFn<F>
+```
+
+## Interface
+
+```ts
+interface DebouncedFn<F> extends Readable<ReturnType<F> | undefined>, Subscribable<ReturnType<F> | undefined> {
+  (...args: Parameters<F>): void
+}
+```
+
+Callable + readable + subscribable. `get()` returns `undefined` until first execution.
+## Common Mistakes
+
+### [HIGH] Using createDebounced on a function
+
+Wrong:
+
+```ts
+createDebounced(fn, 300)
+```
+
+Correct:
+
+```ts
+createDebouncedFn(fn, 300)
+```
+
+createDebounced wraps subscribables; createDebouncedFn wraps callables.
+
+### [MEDIUM] Expecting synchronous return from call
+
+Wrong:
+
+```ts
+const result = debouncedFn()
+```
+
+Correct:
+
+```ts
+debouncedFn(); const result = useSubscription(debouncedFn)
+```
+
+Return value updates after debounced execution via subscription.
+
+### [MEDIUM] Not subscribing to fn result
+
+Wrong:
+
+```ts
+debouncedFn(args) // never read output
+```
+
+Correct:
+
+```ts
+debouncedFn(args); debouncedFn.subscribe(console.log)
+```
+
+DebouncedFn is Subscribable; subscribe or useSubscription to read latest result.
+
+## Source
+
+`src/core/debounced-fn.ts`

package/skills/{createIndexedDbStorage → create-indexed-db-storage}/SKILL.md

@@ -1,8 +1,15 @@
 ---
-name: createIndexedDbStorage
+name: create-indexed-db-storage
 description: >-
-  Create a multi-key reactive handle for IndexedDB with schema validation.
-  Use when persisting state to IndexedDB with async set and sync cached get.
+  Async IndexedDB persistence with cached sync reads.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/web/indexed-db-storage.mdx
+  - letstri/seitu:seitu/src/web/indexed-db-storage.ts
 ---
 
 # createIndexedDbStorage
@@ -57,7 +64,58 @@ interface IndexedDbStorage<O> extends Subscribable<O>, Readable<O>, Writable<Par
   clear: () => Promise<void>
 }
 ```
+## Common Mistakes
+
+### [HIGH] Treating set as synchronous
+
+Wrong:
+
+```ts
+await storage.set(data)
+expect(storage.get()).toEqual(persistedFromDb)
+```
+
+Correct:
+
+```ts
+storage.set(data)
+storage.subscribe(next => { /* react when cache updates */ })
+```
+
+IndexedDB writes are async; get() returns cached value immediately.
+
+### [MEDIUM] Using in Node without fake-indexeddb
+
+Wrong:
+
+```ts
+createIndexedDbStorage({ ... }) // in vitest without polyfill
+```
+
+Correct:
+
+```ts
+import 'fake-indexeddb/auto'
+```
+
+IndexedDB is browser-only; tests need fake-indexeddb polyfill.
+
+### [HIGH] Missing schemas for keys
+
+Wrong:
+
+```ts
+createIndexedDbStorage({ dbName: 'app' })
+```
+
+Correct:
+
+```ts
+createIndexedDbStorage({ dbName: 'app', schemas: { items: z.array(z.string()) }, defaultValues: { items: [] } })
+```
+
+Same as WebStorage — keys must be declared in schemas/defaultValues.
 
 ## Source
 
-`seitu/src/web/indexed-db-storage.ts`
+`src/web/indexed-db-storage.ts`

package/skills/create-is-online/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: create-is-online
+description: >-
+  Reactive navigator.onLine status.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/web/is-online.mdx
+  - letstri/seitu:seitu/src/web/is-online.ts
+---
+
+# createIsOnline
+
+Reactive boolean for `navigator.onLine`. Listens to `online`/`offline` window events.
+
+```ts
+import { createIsOnline } from 'seitu/web'
+
+const online = createIsOnline()
+online.get() // true or false
+online.subscribe(v => console.log(v ? 'online' : 'offline'))
+```
+
+## Interface
+
+```ts
+interface IsOnline extends Subscribable<boolean>, Readable<boolean> {}
+```
+
+No options. Returns `true` during SSR (when `navigator` is undefined). Lazy — only listens to events while subscribed.
+## Common Mistakes
+
+### [MEDIUM] Polling navigator.onLine manually
+
+Wrong:
+
+```ts
+setInterval(() => setOnline(navigator.onLine), 1000)
+```
+
+Correct:
+
+```ts
+const online = createIsOnline()
+online.subscribe(v => setOnline(v))
+```
+
+createIsOnline subscribes to online/offline events.
+
+### [MEDIUM] Assuming onLine means reachable server
+
+Wrong:
+
+```ts
+if (online.get()) fetch('/api') // always succeeds
+```
+
+Correct:
+
+```ts
+if (online.get()) fetch('/api').catch(handleOffline)
+```
+
+onLine is browser connectivity, not server health.
+
+### [LOW] Guarding creation with typeof window
+
+Wrong:
+
+```ts
+const online = typeof window !== 'undefined' ? createIsOnline() : null
+```
+
+Correct:
+
+```ts
+const online = createIsOnline()
+```
+
+Returns false when offline API unavailable; safe at module scope.
+
+## Source
+
+`src/web/is-online.ts`

package/skills/create-media-query/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: create-media-query
+description: >-
+  Reactive CSS media query with SSR defaultMatches.
+type: core
+library: seitu
+library_version: "0.16.0"
+requires:
+  - seitu-overview
+sources:
+  - letstri/seitu:docs/content/docs/web/media-query.mdx
+  - letstri/seitu:seitu/src/web/media-query.ts
+---
+
+# createMediaQuery
+
+Reactive boolean for CSS media queries. Provides type-safe query string with autocomplete for known media features.
+
+```ts
+import { createMediaQuery } from 'seitu/web'
+
+const isDark = createMediaQuery({ query: '(prefers-color-scheme: dark)' })
+const isDesktop = createMediaQuery({ query: '(min-width: 768px)' })
+
+isDark.get() // boolean
+isDark.subscribe(matches => console.log(matches))
+```
+
+## Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `query` | type-safe string | CSS media query |
+| `defaultMatches?` | `boolean` | SSR fallback (default `false`) |
+
+## Interface
+
+```ts
+interface MediaQuery extends Subscribable<boolean>, Readable<boolean> {}
+```
+
+Read-only. Lazy — listens to `change` events only while subscribed.
+
+## Type-safe queries
+
+The `query` option provides autocomplete for standard media features: `min-width`, `max-width`, `prefers-color-scheme`, `orientation`, `hover`, `pointer`, etc. Supports `and`/`,` combinators.
+## Common Mistakes
+
+### [CRITICAL] Missing defaultMatches for SSR
+
+Wrong:
+
+```ts
+createMediaQuery({ query: '(min-width: 768px)' })
+```
+
+Correct:
+
+```ts
+createMediaQuery({ query: '(min-width: 768px)', defaultMatches: true })
+```
+
+get() returns false when window is undefined unless defaultMatches is set.
+
+### [HIGH] Invalid media query string
+
+Wrong:
+
+```ts
+createMediaQuery({ query: '(min-width: 768' })
+```
+
+Correct:
+
+```ts
+createMediaQuery({ query: '(min-width: 768px)' })
+```
+
+Malformed queries throw at creation time in the browser.
+
+### [HIGH] Creating query inside component each render
+
+Wrong:
+
+```ts
+function Layout() {
+  const mq = createMediaQuery({ query: '...' })
+}
+```
+
+Correct:
+
+```ts
+const isDesktop = createMediaQuery({ query: '(min-width: 768px)' })
+```
+
+New matchMedia listener per render; use module-level singleton.
+
+## Source
+
+`src/web/media-query.ts`