kenspeckle 0.1.4 → 0.2.1

package/LICENSE

@@ -19,3 +19,16 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+Third-party notices
+
+Portions of this software are adapted from the following projects, each
+distributed under the MIT License above with its own copyright notice.
+
+runed
+Copyright (c) 2024 Hunter Johnston <https://github.com/huntabyte>
+
+svelte-put
+Copyright (c) 2023-2024 Quang Phan

package/README.md

@@ -3,116 +3,119 @@
 	<img src="docs/assets/banner-light.svg" alt="kenspeckle, adjective, Scots, from Old Norse kennispeki: 1. easily recognised; conspicuous; familiar at sight. 2. (of Svelte utilities) knowable from the name alone.">
 </picture>
 
-Svelte utilities you recognize at sight. One naming convention, no `use` prefix, attachments first-class.
+Svelte utilities you recognize at sight: each one is shaped the way Svelte shapes its own APIs, so it reads like something Svelte might have shipped.
 
-## The sentence test
+## Shaped like Svelte
 
-Every export earns its shape by being said aloud: _"I want a new \___."_
+A utility makes the cut only if Svelte doesn't already handle it. Handled means a Svelte or Kit API covers it (a binding, `on()`, `onDestroy`, `<svelte:document>`, an `$effect` with a returned cleanup), the platform does (`field-sizing`, `:focus-within`), or a few lines of Svelte do, in which case it becomes a [recipe](https://kenspeckle.brandonpittman.workers.dev/docs/recipes) instead of an export.
 
-- "a new **finite state machine**" — speakable, and you drive it with methods → `new FiniteStateMachine()`
-- "a new **element size**" — not a thing you ask for → `elementSize()`
-- "a new **is idle**" — nonsense → `idle()`
+What makes the cut takes the shape Svelte already uses for the same kind of thing. Ask these in order; the first yes decides:
 
-Two rules fall out:
+1. **Is it global browser state?** A singleton with `current`, like `innerWidth` in `svelte/reactivity/window`: `documentVisible.current`. It reads the live value, and on the server it is `undefined`, as Svelte's are. Where a `<svelte:document>` or `<svelte:window>` binding already exists, the singleton earns its place only if modules need to read it outside a component: a polling store that pauses in a hidden tab does, and focus logic, which lives with its element, doesn't.
+2. **Is it a value configured at construction?** A class with `current`, like `new MediaQuery(query)`: `new Idle(60_000)`, `new PersistedState('theme', 'light')`.
+3. **Is it a value that follows another over time?** A class with `.of(fn)`, like `Spring.of(() => number)`, called in an effect root such as component init. It earns the class only if `current` holds something you couldn't produce where the value is written, the way a tween's in-between frames are. A debounced value and a previous value both fail this: each is a value already written, so `debounce()` or a saved copy at the write site covers it.
+4. **Do you drive it with methods?** A class: `new FiniteStateMachine()`, `new StateHistory()`.
+5. **Is it behavior on an element?** An attachment, named for what it does, as `copy` and `fade` are (`dragScroll`, `lockScroll`), or for the event it answers (`clickOutside`). An element value flows into your own `$state` through a callback, the way a function binding does (`bind:clientWidth={null, setWidth}`), never through a box the library owns, and it is named for that value, as a binding is (`scrollEdges`).
+6. **Otherwise**, a plain function, with no `use` prefix, which is a React Hooks rule Svelte doesn't have.
 
-1. **Class** only when "new X" is speakable _and_ you drive it with methods. There are exactly two: `FiniteStateMachine` and `StateHistory`.
-2. **Everything else is a camelCase function.** No `use` prefix — that's a React Hooks rule, and Svelte has no such rule. No `is` prefix either — predicates are bare words read as implicit questions: `mounted()`, `idle()`, `documentVisible()`. The question lives in the library, the answer in your variable: `const isMounted = mounted()`.
+Each shape names the Svelte API it mirrors. An export that can't name one isn't shaped yet.
 
-That's why the name. Kenspeckle things are known at sight; so is every export here. The word is the spec.
+## Attachments, one form
 
-## Attachments, curried
-
-Element-bound utilities are one name in two forms. Options only → returns an [attachment](https://svelte.dev/docs/svelte/@attach). Element first → the imperative helper, cleanup returned.
+An element-bound utility returns an [attachment](https://svelte.dev/docs/svelte/@attach) and has no second form. An attachment is a function of the element, so outside a template you call it on one and get its cleanup back.
 
 ```svelte
 <script>
-	// same import, imperative
-	const cleanup = clickOutside(node, () => close());
+	// outside a template
+	const cleanup = clickOutside(() => close())(node);
 </script>
 
 <div {@attach clickOutside(() => close())}>…</div>
 ```
 
-Value-producing attachments are readable boxes — the factory's return _is_ the attachment, carrying reactive getters:
+An attachment that observes the element hands what it sees to a callback, so the value lives in your state:
 
 ```svelte
 <script>
-	import { elementSize } from 'kenspeckle';
+	import { scrollEdges } from 'kenspeckle';
 
-	const size = elementSize(); // no target yet
+	let atBottom = $state(false);
 </script>
 
-<div {@attach size}>…</div><p>{size.width} × {size.height}</p>
+<div {@attach scrollEdges((edges) => (atBottom = edges.blockEnd))}>…</div>
 ```
 
-The same export works imperatively with a getter: `elementSize(() => node)`. Argument presence picks the mode.
-
 ## Install
 
 ```sh
 npm install kenspeckle
 ```
 
-Peer dependencies: `svelte >= 5.40`, plus `@sveltejs/kit >= 2` for the `kenspeckle/kit` subpath (optional). SSR-safe — value factories return inert defaults on the server.
+Peer dependencies: `svelte >= 5.40`, plus `@sveltejs/kit >= 2` for the `kenspeckle/kit` subpath (optional). SSR-safe — singletons read `undefined` on the server, as Svelte's window values do.
 
 ## What's shipped
 
-Five exports, two entry points. `kenspeckle` is Svelte-only; `kenspeckle/kit` adds the SvelteKit
+Ten exports, two entry points, each documented under [the docs site](https://kenspeckle.brandonpittman.workers.dev/docs). `kenspeckle` is Svelte-only; `kenspeckle/kit` adds the SvelteKit
 pieces, so `$app/navigation` never enters the main entry.
 
-| export                  | form                                   | lineage                    |
-| ----------------------- | -------------------------------------- | -------------------------- |
-| `FiniteStateMachine`    | class, with typed reactive `context`   | runed `FiniteStateMachine` |
-| `copy()` / `copyText()` | attachment + helper                    | svelte-put `copy`          |
-| `viewTransition()`      | function; navigation form under `/kit` | new                        |
-| `viewTransitionName()`  | attachment + helper, `/kit`            | new                        |
-| `retreat()`             | function, returns a disposer, `/kit`   | new                        |
-
-`FiniteStateMachine` gains a typed, `$state`-backed `context` object visible to lifecycle hooks and
+| export                                                                                            | form                                   |
+| ------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| [`FiniteStateMachine`](https://kenspeckle.brandonpittman.workers.dev/docs/finite-state-machine)   | class, with typed reactive `context`   |
+| [`PersistedState`](https://kenspeckle.brandonpittman.workers.dev/docs/persisted-state)            | class, `.current`                      |
+| [`documentVisible`](https://kenspeckle.brandonpittman.workers.dev/docs/document-visible)          | singleton, `.current`                  |
+| [`copy()` / `copyText()`](https://kenspeckle.brandonpittman.workers.dev/docs/copy)                | attachment                             |
+| [`scrollEdges()`](https://kenspeckle.brandonpittman.workers.dev/docs/scroll-edges)                | attachment, edges to a callback        |
+| [`viewTransition()`](https://kenspeckle.brandonpittman.workers.dev/docs/view-transition)          | function; navigation form under `/kit` |
+| [`viewTransitionName()`](https://kenspeckle.brandonpittman.workers.dev/docs/view-transition-name) | attachment, `/kit`                     |
+| [`retreat()`](https://kenspeckle.brandonpittman.workers.dev/docs/view-transition)                 | function, returns a disposer, `/kit`   |
+| [`debounce()`](https://kenspeckle.brandonpittman.workers.dev/docs/debounce)                       | function wrapper                       |
+| [`throttle()`](https://kenspeckle.brandonpittman.workers.dev/docs/throttle)                       | function wrapper                       |
+
+`FiniteStateMachine` has a typed, `$state`-backed `context` object visible to lifecycle hooks and
 guards — the sidecar-data mechanism every real FSM grows, built in.
 
 View transitions are what the package is for so far; they get their own section below.
 
 ## Planned
 
-The rest of the curation. These names are the design, not an API you can call — nothing below has
+The rest of the plan. These names are the design, not an API you can call — nothing below has
 shipped.
 
-| export                                                       | form                                       | lineage                                                  |
-| ------------------------------------------------------------ | ------------------------------------------ | -------------------------------------------------------- |
-| `StateHistory`                                               | class                                      | runed `StateHistory`                                     |
-| `mounted()`                                                  | value factory                              | runed `IsMounted`                                        |
-| `idle()`                                                     | value factory                              | runed `IsIdle`                                           |
-| `documentVisible()`                                          | value factory                              | runed `IsDocumentVisible`                                |
-| `focusWithin()`                                              | attachment, readable box                   | runed `IsFocusWithin`                                    |
-| `inViewport()`                                               | attachment, readable box                   | runed `IsInViewport`                                     |
-| `elementSize()`                                              | attachment, readable box                   | runed `ElementSize`                                      |
-| `elementRect()`                                              | attachment, readable box                   | runed `ElementRect`                                      |
-| `scrollState()`                                              | attachment, readable box; window form      | runed `ScrollState`                                      |
-| `autosize()`                                                 | attachment                                 | runed `TextareaAutosize`                                 |
-| `clickOutside()`                                             | attachment + helper                        | runed `onClickOutside` · svelte-put `clickoutside`       |
-| `intersected()`                                              | attachment + helper                        | runed `useIntersectionObserver` · svelte-put `intersect` |
-| `resized()`                                                  | attachment + helper                        | runed `useResizeObserver` · svelte-put `resize`          |
-| `mutated()`                                                  | attachment + helper                        | runed `useMutationObserver`                              |
-| `shortcut()`                                                 | attachment + helper                        | svelte-put `shortcut`                                    |
-| `lockScroll`                                                 | attachment ≡ helper, stacked lock counting | new                                                      |
-| `dragScroll()`                                               | attachment                                 | svelte-put `dragscroll`                                  |
-| `debounced()` / `throttled()`                                | value factory                              | runed `Debounced` / `Throttled`                          |
-| `debounce()` / `throttle()`                                  | function wrapper                           | runed `useDebounce` / `useThrottle`                      |
-| `previous()`                                                 | value factory                              | runed `Previous`                                         |
-| `activeElement()`                                            | value factory                              | runed `ActiveElement`                                    |
-| `pressedKeys()`                                              | value factory                              | runed `PressedKeys`                                      |
-| `persisted()`                                                | value factory                              | runed `PersistedState`                                   |
-| `animationFrames()`                                          | value factory                              | runed `AnimationFrames`                                  |
-| `geolocation()`                                              | value factory                              | runed `useGeolocation`                                   |
-| `listen()`                                                   | wiring                                     | runed `useEventListener`                                 |
-| `interval()`                                                 | wiring                                     | runed `useInterval`                                      |
-| `searchParams()` + helpers                                   | value factory                              | runed `useSearchParams`                                  |
-| `watch` / `watchOnce` / `extract` / `onCleanup` / `boolAttr` | unchanged                                  | runed                                                    |
-
-Dropped, deliberately: runed's `Context` — Svelte ≥ 5.40's `createContext` returns a typed
-`[get, set]` pair and covers it. runed's `resource` waits in the backlog — SvelteKit remote functions
-cover the server-data case; it returns only if a real client-only async need shows up.
+| export                | form                                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------------------- |
+| `StateHistory`        | class: `new StateHistory(get, set)`, `.undo()`, `.redo()`                                         |
+| `Idle`                | class: `new Idle(ms)`, `.current`                                                                 |
+| `AsyncPersistedState` | class over IndexedDB: `await` it, or read `.current`, `.loading`, `.error`, like a remote `query` |
+| `CurrentPosition`     | class: `new CurrentPosition(options)`, `.current`                                                 |
+| `pressedKeys`         | singleton, read like a set: `.has(key)`                                                           |
+| `clickOutside()`      | attachment                                                                                        |
+| `shortcut()`          | attachment                                                                                        |
+| `lockScroll`          | attachment ≡ helper, stacked lock counting                                                        |
+| `dragScroll()`        | attachment                                                                                        |
+
+Dropped, deliberately, because Svelte, Kit or the platform already handles it:
+
+- `Context`: Svelte ≥ 5.40's `createContext` returns a typed `[get, set]` pair.
+- `Debounced` / `Throttled`: `debounce()` / `throttle()` writing into a `$state`, with any effect that follows a source kept in the component that owns it.
+- `elementSize`, `elementRect`, `resized`: the dimension bindings (`bind:clientWidth`, `bind:contentRect`, `bind:borderBoxSize`) already measure with a `ResizeObserver`.
+- `autosize`: CSS `field-sizing: content`, Baseline since June 2026.
+- `intersected`, `inViewport`: an inline attachment that creates an `IntersectionObserver` and returns its `disconnect`.
+- `mutated`: the same inline attachment around a `MutationObserver`.
+- `focusWithin`: CSS `:focus-within` for styling, and `onfocusin` / `onfocusout` with `relatedTarget` for a value.
+- `scrollState`, except its edges: `onscroll` gives an element's position, a comparison with the last value gives direction, and `<svelte:window bind:scrollY>` covers the window.
+- `activeElement`: `<svelte:document bind:activeElement />`, since focus logic lives in the component that holds the element.
+- `Previous`: save the old value where you write the new one (`previous = count; count = next`); for a prop you don't write, an `$effect.pre` does it.
+- `mounted`: `onMount` setting a `$state`.
+- `listen`: `on()` from `svelte/events`.
+- `interval`, `animationFrames`: an `$effect` that starts the timer or loop and returns its cleanup.
+- `onCleanup`: `onDestroy`, or an effect's returned cleanup.
+- `watch` / `watchOnce`: an effect responds to state being a certain way, not to it changing; handle the change where it happens.
+- `extract`: nothing here takes a value-or-getter.
+- `boolAttr`: Svelte omits nullish attributes, so `data-x={flag || undefined}`.
+
+The [recipes](https://kenspeckle.brandonpittman.workers.dev/docs/recipes) page spells out the replacements for `autosize`, `intersected`, `mutated`, `focusWithin` and `Previous`.
+
+Waiting in the backlog: `resource`, since SvelteKit remote functions cover the server-data case, and `searchParams`, since Kit's `page.url.searchParams` and `goto` cover reads and writes until a typed layer earns its place.
 
 ## View transitions
 
@@ -195,11 +198,11 @@ scoped rather than left in static CSS.
 ```
 
 `when` claims only for navigations it accepts; `onArrival` claims inside the update callback instead,
-for an element that mounts during the transition. The imperative form takes the element first and
-returns a disposer:
+for an element that mounts during the transition. Outside a template, call the attachment on the
+element to get its disposer:
 
 ```js
-const dispose = viewTransitionName(element, 'back-button');
+const dispose = viewTransitionName('back-button')(element);
 ```
 
 **Claims are navigation-only.** The registration form drives the capture and arrival phases;
@@ -208,18 +211,16 @@ const dispose = viewTransitionName(element, 'back-button');
 
 ## Claude Code plugin
 
-This repo doubles as a Claude Code plugin. `skills/view-transitions/` is the
-agent-facing guide to the view-transition tier — the `data-view-transition`
-contract, `viewTransitionName` claims and their phases, the duplicate-name
-abort, and the list of things the library already handles so an agent stops
-reimplementing them. Point a marketplace entry at this repo
+This repo doubles as a Claude Code plugin with two agent-facing guides.
+`skills/view-transitions/` covers the view-transition tier — the
+`data-view-transition` contract, `viewTransitionName` claims and their phases,
+the duplicate-name abort, and the list of things the library already handles so
+an agent stops reimplementing them. `skills/finite-state-machine/` covers
+`FiniteStateMachine` — the always-transitions rule, the `'*'` re-entry hazard,
+lifecycle ordering and context. Point a marketplace entry at this repo
 (`.claude-plugin/plugin.json` is at the root) and it installs as `kenspeckle`,
-invoked as `/kenspeckle:view-transitions`.
+invoked as `/kenspeckle:view-transitions` and `/kenspeckle:finite-state-machine`.
+It bundles no MCP server; for the Svelte MCP, install the official `svelte`
+plugin from [`sveltejs/ai-tools`](https://github.com/sveltejs/ai-tools).
 
 The skill and the code ship in the same change, same rule as the docs pages.
-
-## Provenance
-
-kenspeckle is a curation, not a fork. [runed](https://runed.dev) has genuinely useful utilities under three naming regimes at once — PascalCase classes, bare functions, and React-style `use` hooks, with pairs like `Debounced` / `useDebounce` coexisting. [svelte-put](https://svelte-put.vnphanquang.com) has good actions from the Svelte 4 era, before attachments existed. kenspeckle reshapes both pools under one convention and adds what neither ships: attachments as a first-class layer.
-
-Portions adapted from runed (MIT) and svelte-put (MIT). kenspeckle is MIT.

package/dist/copy.d.ts

@@ -1,4 +1,3 @@
-import type { Attachment } from 'svelte/attachments';
 export type CopyText = string | ((node: HTMLElement) => string | Promise<string>);
 export interface CopyOptions<K extends keyof HTMLElementEventMap = 'click'> {
     text?: CopyText;
@@ -7,5 +6,4 @@ export interface CopyOptions<K extends keyof HTMLElementEventMap = 'click'> {
     onCopy?: (text: string) => void;
 }
 export declare function copyText(text: string): Promise<void>;
-export declare function copy<K extends keyof HTMLElementEventMap = 'click'>(options?: CopyOptions<K>): Attachment<HTMLElement>;
-export declare function copy<K extends keyof HTMLElementEventMap = 'click'>(node: HTMLElement, options?: CopyOptions<K>): () => void;
+export declare function copy<K extends keyof HTMLElementEventMap = 'click'>(options?: CopyOptions<K>): (node: HTMLElement) => () => void;

package/dist/copy.js

@@ -15,26 +15,21 @@ export async function copyText(text) {
         document.body.removeChild(el);
     }
 }
-export function copy(nodeOrOptions, maybeOptions) {
-    if (typeof Element !== 'undefined' && nodeOrOptions instanceof Element) {
-        return wire(nodeOrOptions, maybeOptions);
-    }
-    const options = nodeOrOptions;
-    return (node) => wire(node, options);
-}
-function wire(node, options = {}) {
-    const { text, event, enabled = true, onCopy } = options;
-    if (!enabled)
-        return () => { };
-    const events = (event === undefined ? ['click'] : Array.isArray(event) ? event : [event]);
-    async function handler() {
-        const resolved = typeof text === 'function' ? await text(node) : (text ?? node.textContent ?? '');
-        await copyText(resolved);
-        onCopy?.(resolved);
-    }
-    const offs = events.map((e) => on(node, e, handler));
-    return () => {
-        for (const off of offs)
-            off();
+export function copy(options = {}) {
+    return (node) => {
+        const { text, event, enabled = true, onCopy } = options;
+        if (!enabled)
+            return () => { };
+        const events = (event === undefined ? ['click'] : Array.isArray(event) ? event : [event]);
+        async function handler() {
+            const resolved = typeof text === 'function' ? await text(node) : (text ?? node.textContent ?? '');
+            await copyText(resolved);
+            onCopy?.(resolved);
+        }
+        const offs = events.map((e) => on(node, e, handler));
+        return () => {
+            for (const off of offs)
+                off();
+        };
     };
 }

package/dist/debounce.svelte.d.ts

@@ -0,0 +1,29 @@
+export type DebouncedFunction<Args extends unknown[], Return> = {
+    (...args: Args): Promise<Awaited<Return>>;
+    readonly pending: boolean;
+    flush(): void;
+    cancel(): void;
+};
+export declare const DEFAULT_WAIT = 250;
+/**
+ * `wait` is a getter so `FiniteStateMachine.debounce` can take a different wait on each call.
+ * `leading` runs a call at once when no window is open, and the window it opens is fixed: later
+ * calls wait for it to end instead of restarting it.
+ */
+export declare class Scheduler<Args extends unknown[], Return> {
+    #private;
+    /**
+     * `reactive: false` keeps `pending` out of Svelte's graph, so a `$derived` or template expression
+     * can call the scheduler: writing `$state` there throws `state_unsafe_mutation`.
+     */
+    constructor(callback: (...args: Args) => Return, wait: () => number, { leading, reactive }?: {
+        leading?: boolean;
+        reactive?: boolean;
+    });
+    get pending(): boolean;
+    call(...args: Args): Promise<Awaited<Return>>;
+    flush(): void;
+    /** The promise is left unsettled: rejecting would be unhandled in every fire-and-forget caller. */
+    cancel(): void;
+}
+export declare function debounce<Args extends unknown[], Return>(callback: (...args: Args) => Return, wait?: number): DebouncedFunction<Args, Return>;

package/dist/debounce.svelte.js

@@ -0,0 +1,105 @@
+export const DEFAULT_WAIT = 250;
+/** `Promise.withResolvers` would raise the runtime floor to Safari 17.4 and Node 22. */
+function withResolvers() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/**
+ * `wait` is a getter so `FiniteStateMachine.debounce` can take a different wait on each call.
+ * `leading` runs a call at once when no window is open, and the window it opens is fixed: later
+ * calls wait for it to end instead of restarting it.
+ */
+export class Scheduler {
+    #callback;
+    #wait;
+    #leading;
+    #timer;
+    /** Plain, so a call made inside an `$effect` doesn't make the effect depend on it. */
+    #scheduled;
+    #reactive;
+    #tracked = $state(false);
+    #untracked = false;
+    /**
+     * `reactive: false` keeps `pending` out of Svelte's graph, so a `$derived` or template expression
+     * can call the scheduler: writing `$state` there throws `state_unsafe_mutation`.
+     */
+    constructor(callback, wait, { leading = false, reactive = true } = {}) {
+        this.#callback = callback;
+        this.#wait = wait;
+        this.#leading = leading;
+        this.#reactive = reactive;
+    }
+    get pending() {
+        return this.#pending;
+    }
+    get #pending() {
+        return this.#reactive ? this.#tracked : this.#untracked;
+    }
+    set #pending(value) {
+        if (this.#reactive)
+            this.#tracked = value;
+        else
+            this.#untracked = value;
+    }
+    call(...args) {
+        if (this.#leading && this.#timer === undefined) {
+            const deferred = withResolvers();
+            this.#start();
+            this.#run({ args, deferred });
+            return deferred.promise;
+        }
+        const deferred = this.#scheduled?.deferred ?? withResolvers();
+        this.#scheduled = { args, deferred };
+        this.#pending = true;
+        if (!this.#leading)
+            this.#start();
+        return deferred.promise;
+    }
+    flush() {
+        clearTimeout(this.#timer);
+        this.#elapse();
+    }
+    /** The promise is left unsettled: rejecting would be unhandled in every fire-and-forget caller. */
+    cancel() {
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#scheduled = undefined;
+        this.#pending = false;
+    }
+    #start() {
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => this.#elapse(), this.#wait());
+    }
+    #elapse() {
+        this.#timer = undefined;
+        const scheduled = this.#scheduled;
+        if (scheduled === undefined)
+            return;
+        this.#scheduled = undefined;
+        this.#pending = false;
+        if (this.#leading)
+            this.#start();
+        this.#run(scheduled);
+    }
+    #run({ args, deferred }) {
+        try {
+            deferred.resolve(this.#callback(...args));
+        }
+        catch (error) {
+            deferred.reject(error);
+        }
+    }
+}
+export function debounce(callback, wait = DEFAULT_WAIT) {
+    const scheduler = new Scheduler(callback, () => wait);
+    return Object.defineProperties((...args) => scheduler.call(...args), {
+        pending: { get: () => scheduler.pending },
+        flush: { value: () => scheduler.flush() },
+        cancel: { value: () => scheduler.cancel() }
+    });
+}

package/dist/document-visible.d.ts

@@ -0,0 +1,4 @@
+export interface DocumentVisible {
+    readonly current: boolean | undefined;
+}
+export declare const documentVisible: DocumentVisible;

package/dist/document-visible.js

@@ -0,0 +1,12 @@
+import { BROWSER } from 'esm-env';
+import { on } from 'svelte/events';
+import { createSubscriber } from 'svelte/reactivity';
+const subscribe = createSubscriber((update) => on(document, 'visibilitychange', update));
+export const documentVisible = {
+    get current() {
+        if (!BROWSER)
+            return undefined;
+        subscribe();
+        return document.visibilityState === 'visible';
+    }
+};

package/dist/finite-state-machine.svelte.js

@@ -1,4 +1,5 @@
 import { DEV } from 'esm-env';
+import { DEFAULT_WAIT, Scheduler } from './debounce.svelte.js';
 export class FiniteStateMachine {
     #current = $state();
     #context = $state();
@@ -35,24 +36,14 @@ export class FiniteStateMachine {
             this.#transition(target, event, args);
         return this.#current;
     };
-    #timeouts = {};
-    debounce = (event, wait = 500, ...args) => {
-        const pending = this.#timeouts[event];
-        if (pending)
-            clearTimeout(pending.id);
-        const resolvers = pending?.resolvers ?? [];
-        return new Promise((resolve) => {
-            resolvers.push(resolve);
-            this.#timeouts[event] = {
-                id: setTimeout(() => {
-                    delete this.#timeouts[event];
-                    const state = this.send(event, ...args);
-                    for (const r of resolvers)
-                        r(state);
-                }, wait),
-                resolvers
-            };
+    #debounced = {};
+    debounce = (event, wait = DEFAULT_WAIT, ...args) => {
+        const debounced = (this.#debounced[event] ??= {
+            wait,
+            scheduler: new Scheduler((...args) => this.send(event, ...args), () => debounced.wait, { reactive: false })
         });
+        debounced.wait = wait;
+        return debounced.scheduler.call(...args);
     };
     #transition(to, event, args) {
         const from = this.#current;

package/dist/index.d.ts

@@ -1,6 +1,16 @@
 export { copy, copyText } from './copy.js';
 export type { CopyOptions, CopyText } from './copy.js';
+export { debounce } from './debounce.svelte.js';
+export type { DebouncedFunction } from './debounce.svelte.js';
+export { documentVisible } from './document-visible.js';
+export type { DocumentVisible } from './document-visible.js';
 export { FiniteStateMachine } from './finite-state-machine.svelte.js';
 export type { Action, ActionMeta, EnterMeta, EventMap, ExitMeta, StateHandler, Transition } from './finite-state-machine.svelte.js';
+export { PersistedState } from './persisted-state.svelte.js';
+export type { PersistedStateOptions } from './persisted-state.svelte.js';
+export { scrollEdges } from './scroll-edges.js';
+export type { ScrollEdges, ScrollEdgesOptions } from './scroll-edges.js';
+export { throttle } from './throttle.svelte.js';
+export type { ThrottledFunction } from './throttle.svelte.js';
 export { viewTransition } from './view-transition.js';
 export type { StartViewTransition, ViewTransitionOptions, ViewTransitionUpdate } from './view-transition.js';

package/dist/index.js

@@ -1,3 +1,8 @@
 export { copy, copyText } from './copy.js';
+export { debounce } from './debounce.svelte.js';
+export { documentVisible } from './document-visible.js';
 export { FiniteStateMachine } from './finite-state-machine.svelte.js';
+export { PersistedState } from './persisted-state.svelte.js';
+export { scrollEdges } from './scroll-edges.js';
+export { throttle } from './throttle.svelte.js';
 export { viewTransition } from './view-transition.js';

package/dist/kit/view-transition-name.d.ts

@@ -1,4 +1,3 @@
-import type { Attachment } from 'svelte/attachments';
 import type { Navigation } from './types.js';
 export interface ViewTransitionNameOptions {
     /** Only claim the name for navigations this returns true for. */
@@ -11,6 +10,5 @@ type Phase = 'capture' | 'arrival';
 export declare function beginPhase(navigation: Navigation, phase: Phase): void;
 /** @internal */
 export declare function endTransition(): void;
-export declare function viewTransitionName(name: string, options?: ViewTransitionNameOptions): Attachment<HTMLElement>;
-export declare function viewTransitionName(element: HTMLElement, name: string, options?: ViewTransitionNameOptions): () => void;
+export declare function viewTransitionName(name: string, options?: ViewTransitionNameOptions): (element: HTMLElement) => () => void;
 export {};

package/dist/kit/view-transition-name.js

@@ -28,21 +28,16 @@ export function endTransition() {
     for (const claim of claims)
         release(claim);
 }
-function wire(element, name, options = {}) {
-    const claim = { element, name, options, named: false };
-    claims.add(claim);
-    // An element mounting mid-transition registers after its phase already swept.
-    if (current && wanted(claim, current.phase, current.navigation))
-        apply(claim);
-    return () => {
-        release(claim);
-        claims.delete(claim);
+export function viewTransitionName(name, options = {}) {
+    return (element) => {
+        const claim = { element, name, options, named: false };
+        claims.add(claim);
+        /** An element mounting mid-transition registers after its phase already swept. */
+        if (current && wanted(claim, current.phase, current.navigation))
+            apply(claim);
+        return () => {
+            release(claim);
+            claims.delete(claim);
+        };
     };
 }
-export function viewTransitionName(first, second, third) {
-    if (typeof Element !== 'undefined' && first instanceof Element) {
-        return wire(first, second, third);
-    }
-    const options = second;
-    return (element) => wire(element, first, options);
-}

package/dist/persisted-state.svelte.d.ts

@@ -0,0 +1,9 @@
+export interface PersistedStateOptions {
+    storage?: 'local' | 'session';
+}
+export declare class PersistedState<T> {
+    #private;
+    constructor(key: string, initial: T, options?: PersistedStateOptions);
+    get current(): T;
+    set current(value: T);
+}

package/dist/persisted-state.svelte.js

@@ -0,0 +1,129 @@
+import { parse, stringify } from 'devalue';
+import { BROWSER, DEV } from 'esm-env';
+import { untrack } from 'svelte';
+import { on } from 'svelte/events';
+import { createSubscriber } from 'svelte/reactivity';
+const probe = Symbol();
+/**
+ * Freezing a `$state` proxy throws only after its target is already non-extensible, which breaks the
+ * caller's state. The proxy refuses a non-enumerable property before touching its target, so this
+ * probe tells one apart without changing anything.
+ */
+function isStateProxy(value) {
+    try {
+        const descriptor = { value: undefined, enumerable: false, configurable: true, writable: true };
+        if (Reflect.defineProperty(value, probe, descriptor))
+            Reflect.deleteProperty(value, probe);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function freeze(value) {
+    if (!DEV || value === null || typeof value !== 'object')
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if ((Array.isArray(value) || prototype === Object.prototype || prototype === null) &&
+        !isStateProxy(value)) {
+        Object.freeze(value);
+    }
+    return value;
+}
+export class PersistedState {
+    #key;
+    #initial;
+    #area;
+    #value;
+    /** `undefined` until the first read, so a stored `null` (an empty key) still counts as seen. */
+    #seen;
+    /** Wakes readers after an own write, including one that never reached storage. */
+    #version = $state.raw(0);
+    /** Set while `#value` holds a write storage refused, so any later write to the key replaces it. */
+    #unsaved = false;
+    #subscribe = createSubscriber((update) => on(window, 'storage', (event) => {
+        if (event.storageArea !== this.#storage())
+            return;
+        if (event.key !== null && event.key !== this.#key)
+            return;
+        /**
+         * The write may have stored the very string `#seen` captured at the failure, which the getter
+         * cannot tell apart from no write at all.
+         */
+        if (this.#unsaved) {
+            this.#unsaved = false;
+            this.#seen = undefined;
+        }
+        update();
+    }));
+    constructor(key, initial, options = {}) {
+        this.#key = key;
+        this.#initial = freeze(initial);
+        this.#area = `${options.storage ?? 'local'}Storage`;
+        this.#value = initial;
+    }
+    #storage() {
+        try {
+            return window[this.#area];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** `undefined` when storage refuses the read. */
+    #read() {
+        try {
+            return this.#storage()?.getItem(this.#key) ?? null;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #fail(error) {
+        if (DEV)
+            console.warn(`PersistedState could not write "${this.#key}"`, error);
+        /** Marks what storage still holds as seen, so the next read keeps the in-memory value. */
+        this.#seen = this.#read();
+        this.#unsaved = true;
+    }
+    get current() {
+        void this.#version;
+        if (!BROWSER)
+            return this.#value;
+        this.#subscribe();
+        const raw = this.#read();
+        if (raw === undefined || raw === this.#seen)
+            return this.#value;
+        this.#seen = raw;
+        try {
+            this.#value = raw === null ? this.#initial : freeze(parse(raw));
+        }
+        catch {
+            this.#value = this.#initial;
+        }
+        return this.#value;
+    }
+    set current(value) {
+        const raw = stringify(value);
+        this.#value = freeze(value);
+        /** Untracked, so an effect that assigns `current` does not come to depend on its own write and rerun forever. */
+        this.#version = untrack(() => this.#version) + 1;
+        if (!BROWSER)
+            return;
+        const storage = this.#storage();
+        if (!storage) {
+            this.#fail(new Error(`${this.#area} is unavailable`));
+            return;
+        }
+        try {
+            storage.setItem(this.#key, raw);
+        }
+        catch (error) {
+            this.#fail(error);
+            return;
+        }
+        this.#seen = raw;
+        this.#unsaved = false;
+        window.dispatchEvent(new StorageEvent('storage', { key: this.#key, newValue: raw, storageArea: storage }));
+    }
+}

package/dist/scroll-edges.d.ts

@@ -0,0 +1,10 @@
+export interface ScrollEdges {
+    blockStart: boolean;
+    blockEnd: boolean;
+    inlineStart: boolean;
+    inlineEnd: boolean;
+}
+export interface ScrollEdgesOptions {
+    offset?: number;
+}
+export declare function scrollEdges(callback: (edges: ScrollEdges) => void, options?: ScrollEdgesOptions): (node: HTMLElement) => () => void;

package/dist/scroll-edges.js

@@ -0,0 +1,88 @@
+import { untrack } from 'svelte';
+import { on } from 'svelte/events';
+export function scrollEdges(callback, options = {}) {
+    return (node) => {
+        /** The extra pixel absorbs the sub-pixel gap a fractional box height leaves at maximum scrollTop. */
+        const reach = (options.offset ?? 0) + 1;
+        let last;
+        function compute() {
+            /** A hidden or detached scroller measures 0 by 0, which would read as every edge reached; its own ResizeObserver recomputes once it renders. */
+            if (node.clientWidth === 0 && node.clientHeight === 0)
+                return;
+            const style = getComputedStyle(node);
+            const flex = style.display.includes('flex');
+            const column = style.flexDirection.startsWith('column');
+            const wrapReverse = style.flexWrap === 'wrap-reverse';
+            /** A reversed flex axis moves the scroll origin to that axis's end edge. */
+            const blockFromEnd = flex && (column ? style.flexDirection === 'column-reverse' : wrapReverse);
+            const inlineFromEnd = flex && (column ? wrapReverse : style.flexDirection === 'row-reverse');
+            /** scrollTop and scrollLeft run negative from 0 when the origin sits on the bottom or right edge. */
+            const inlineOriginRight = (style.direction === 'rtl') !== inlineFromEnd;
+            const blockMax = node.scrollHeight - node.clientHeight;
+            const inlineMax = node.scrollWidth - node.clientWidth;
+            /** Elastic overscroll pushes the position past either end, which must not count as distance. */
+            const blockScrolled = clamp(blockFromEnd ? -node.scrollTop : node.scrollTop, blockMax);
+            const inlineScrolled = clamp(inlineOriginRight ? -node.scrollLeft : node.scrollLeft, inlineMax);
+            const fromBlockStart = blockFromEnd ? blockMax - blockScrolled : blockScrolled;
+            const fromInlineStart = inlineFromEnd ? inlineMax - inlineScrolled : inlineScrolled;
+            const edges = {
+                blockStart: fromBlockStart < reach,
+                blockEnd: blockMax - fromBlockStart < reach,
+                inlineStart: fromInlineStart < reach,
+                inlineEnd: inlineMax - fromInlineStart < reach
+            };
+            if (last?.blockStart === edges.blockStart &&
+                last.blockEnd === edges.blockEnd &&
+                last.inlineStart === edges.inlineStart &&
+                last.inlineEnd === edges.inlineEnd) {
+                return;
+            }
+            last = edges;
+            callback(edges);
+        }
+        const resize = new ResizeObserver(compute);
+        resize.observe(node);
+        for (const child of node.children)
+            resize.observe(child);
+        const mutation = new MutationObserver((records) => {
+            for (const record of records) {
+                if (record.target !== node)
+                    continue;
+                /** replaceChildren can list a kept child as both removed and added, so it must be observed last. */
+                for (const removed of record.removedNodes) {
+                    if (removed instanceof Element)
+                        resize.unobserve(removed);
+                }
+                for (const added of record.addedNodes) {
+                    if (added instanceof Element)
+                        resize.observe(added);
+                }
+            }
+            compute();
+        });
+        /** Rewritten text, a margin, a position or a grandchild overflowing a fixed-size child changes the scroll extent without resizing any observed box. */
+        mutation.observe(node, {
+            childList: true,
+            characterData: true,
+            attributes: true,
+            subtree: true
+        });
+        const page = node === node.ownerDocument.scrollingElement;
+        /** The browser fires a viewport scroll at the document, never at the root element that scrolls. */
+        const off = on(page ? node.ownerDocument : node, 'scroll', compute);
+        const view = node.ownerDocument.defaultView;
+        /** The root element's box follows its content, not the viewport, so a window that grows or shrinks without moving the scroll position resizes nothing observed. */
+        const offResize = page && view ? on(view, 'resize', compute) : undefined;
+        /** The first compute runs inside the attachment's effect, so state the callback reads would otherwise re-create the attachment on every write. */
+        untrack(compute);
+        return () => {
+            off();
+            offResize?.();
+            resize.disconnect();
+            mutation.disconnect();
+        };
+    };
+}
+function clamp(value, max) {
+    return Math.min(Math.max(value, 0), max);
+}

package/dist/throttle.svelte.d.ts

@@ -0,0 +1,6 @@
+export type ThrottledFunction<Args extends unknown[], Return> = {
+    (...args: Args): Promise<Awaited<Return>>;
+    readonly pending: boolean;
+    cancel(): void;
+};
+export declare function throttle<Args extends unknown[], Return>(callback: (...args: Args) => Return, wait?: number): ThrottledFunction<Args, Return>;

package/dist/throttle.svelte.js

@@ -0,0 +1,8 @@
+import { DEFAULT_WAIT, Scheduler } from './debounce.svelte.js';
+export function throttle(callback, wait = DEFAULT_WAIT) {
+    const scheduler = new Scheduler(callback, () => wait, { leading: true });
+    return Object.defineProperties((...args) => scheduler.call(...args), {
+        pending: { get: () => scheduler.pending },
+        cancel: { value: () => scheduler.cancel() }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kenspeckle",
-	"version": "0.1.4",
+	"version": "0.2.1",
 	"description": "Svelte 5 utilities under one naming convention: attachments first-class, view transitions, and a state machine with context.",
 	"license": "MIT",
 	"author": "Brandon Pittman <brandon@brandonpittman.com>",
@@ -8,7 +8,7 @@
 		"type": "git",
 		"url": "git+https://github.com/brandonpittman/kenspeckle.git"
 	},
-	"homepage": "https://github.com/brandonpittman/kenspeckle#readme",
+	"homepage": "https://kenspeckle.brandonpittman.workers.dev/docs",
 	"bugs": "https://github.com/brandonpittman/kenspeckle/issues",
 	"scripts": {
 		"dev": "vite dev",
@@ -96,6 +96,7 @@
 		"utilities"
 	],
 	"dependencies": {
+		"devalue": "^5.8.1 || ^6",
 		"esm-env": "^1.2.2"
 	}
 }