kenspeckle 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Pittman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

package/README.md

@@ -1,65 +1,199 @@
-# Svelte library
+<picture>
+	<source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
+	<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>
 
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+Svelte utilities you recognize at sight. One naming convention, no `use` prefix, attachments first-class.
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+## The sentence test
 
-## Creating a project
+Every export earns its shape by being said aloud: _"I want a new \___."_
 
-If you're seeing this, you've probably already done this step. Congrats!
+- "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()`
 
-```sh
-# create a new project in the current directory
-npx sv create
+Two rules fall out:
+
+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()`.
+
+That's why the name. Kenspeckle things are known at sight; so is every export here. The word is the spec.
+
+## Attachments, curried
 
-# create a new project in my-app
-npx sv create my-app
+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.
+
+```svelte
+<script>
+	// same import, imperative
+	const cleanup = clickOutside(node, () => close());
+</script>
+
+<div {@attach clickOutside(() => close())}>…</div>
 ```
 
-To recreate this project with the same configuration:
+Value-producing attachments are readable boxes — the factory's return _is_ the attachment, carrying reactive getters:
 
-```sh
-# recreate this project
-npx sv@0.16.3 create --template library --types ts --add prettier eslint vitest="usages:unit,component" playwright sveltekit-adapter="adapter:cloudflare+cfTarget:workers" mdsvex mcp="ide:claude-code+setup:remote" experimental="versions:none+features:async,remoteFunctions,explicitEnvironmentVariables,handleRenderingErrors" --install npm kenspeckle
+```svelte
+<script>
+	import { elementSize } from 'kenspeckle';
+
+	const size = elementSize(); // no target yet
+</script>
+
+<div {@attach size}>…</div><p>{size.width} × {size.height}</p>
 ```
 
-## Developing
+The same export works imperatively with a getter: `elementSize(() => node)`. Argument presence picks the mode.
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+## Install
 
 ```sh
-npm run dev
+npm install kenspeckle
+```
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+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.
+
+## What's inside
+
+| export                                                       | form                                       | lineage                                                  |
+| ------------------------------------------------------------ | ------------------------------------------ | -------------------------------------------------------- |
+| `FiniteStateMachine`                                         | class, with typed reactive `context`       | runed `FiniteStateMachine`                               |
+| `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`                              |
+| `copy()`                                                     | attachment + helper                        | svelte-put `copy`                                        |
+| `shortcut()`                                                 | attachment + helper                        | svelte-put `shortcut`                                    |
+| `lockScroll`                                                 | attachment ≡ helper, stacked lock counting | new                                                      |
+| `dragScroll()`                                               | attachment                                 | svelte-put `dragscroll`                                  |
+| `viewTransition()`                                           | function; navigation form under `/kit`     | new                                                      |
+| `viewTransitionName()`                                       | attachment + helper                        | new                                                      |
+| `retreat()`                                                  | function, returns a disposer               | new                                                      |
+| `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.
+
+`FiniteStateMachine` gains a typed, `$state`-backed `context` object visible to lifecycle hooks and guards — the sidecar-data mechanism every real FSM grows, built in.
+
+View transitions ship in two tiers. `viewTransition(update)` animates a state change within a route; the SvelteKit navigation form, plus `viewTransitionName` and `retreat`, come from the `kenspeckle/kit` subpath — separate so `$app/navigation` never enters the main entry. Both tiers fall back cleanly: with no `document.startViewTransition`, or under `prefers-reduced-motion`, the update still runs, untransitioned.
+
+## View transitions
+
+Two entry points. `kenspeckle` exports the same-route form; `kenspeckle/kit` adds the SvelteKit
+navigation form, so `$app/navigation` never enters the main entry. The `/kit` subpath expects
+`@sveltejs/kit` — an optional peer.
+
+### The contract
+
+One attribute on `<html>`, absent when idle:
+
+| `data-view-transition` | written by                                            |
+| ---------------------- | ----------------------------------------------------- |
+| `forward`              | a navigation                                          |
+| `retreat`              | a navigation the predicate claims, or a Back popstate |
+| `step-forward`         | `viewTransition(update)`                              |
+| `step-retreat`         | `viewTransition(update, { retreat: true })`           |
+
+Every animation is yours, keyed off that value. An unprefixed `::view-transition-old|new(name)` rule
+matches both kinds, so scope it when a step and a navigation must differ.
+
+```css
+html[data-view-transition='forward']::view-transition-old(root) {
+	animation: slide-out-left 300ms;
+}
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+### Navigations
 
-## Building
+Register once, from the root layout:
 
-To build your library:
+```svelte
+<script>
+	import { viewTransition } from 'kenspeckle/kit';
 
-```sh
-npm pack
+	viewTransition();
+</script>
 ```
 
-To create a production version of your showcase app:
+Direction is a predicate, never a flag: Kit skips `beforeNavigate` for a navigation begun while
+another is in flight, so a flag set at click time can be stranded and reverse a later navigation.
+`retreat()` returns an identity-guarded disposer, shaped for `$effect` cleanup.
 
-```sh
-npm run build
+```svelte
+<script>
+	import { retreat } from 'kenspeckle/kit';
+
+	$effect(() => retreat((navigation) => navigation.to?.route.id === '/'));
+</script>
 ```
 
-You can preview the production build with `npm run preview`.
+A Back popstate is a retreat without asking. A Forward popstate is not.
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+### Steps within a route
 
-## Publishing
+`onNavigate` never fires for a wizard advancing its own state, so drive the primitive directly:
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+```svelte
+<script>
+	import { viewTransition } from 'kenspeckle';
 
-To publish your library to [npm](https://www.npmjs.com):
+	let step = $state(0);
+	const go = (delta) => viewTransition(() => (step += delta), { retreat: delta < 0 });
+</script>
+```
 
-```sh
-npm publish
+The update callback suspends rendering until it settles, which past half a second reads as a hang —
+`deadline` (600ms) skips the transition rather than let it. With no `document.startViewTransition`,
+or under `prefers-reduced-motion`, the update still runs, untransitioned, and no attribute is
+written.
+
+### Named elements
+
+`viewTransitionName` claims `view-transition-name` for the duration of a transition and releases it
+after. Two elements holding one name silently abort the whole transition, which is why claims are
+scoped rather than left in static CSS.
+
+```svelte
+<button {@attach viewTransitionName('back-button')}>Back</button>
+```
+
+`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:
+
+```js
+const dispose = viewTransitionName(element, 'back-button');
 ```
+
+**Claims are navigation-only.** The registration form drives the capture and arrival phases;
+`viewTransition(update)` on a same-route step names nothing. Morph a stepping element with static
+`view-transition-name` in CSS instead.
+
+## 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

@@ -0,0 +1,11 @@
+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;
+    event?: K | K[];
+    enabled?: boolean;
+    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;

package/dist/copy.js

@@ -0,0 +1,40 @@
+import { on } from 'svelte/events';
+export async function copyText(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+    }
+    catch {
+        const el = document.createElement('textarea');
+        el.value = text;
+        el.setAttribute('readonly', '');
+        el.style.position = 'absolute';
+        el.style.left = '-9999px';
+        document.body.appendChild(el);
+        el.select();
+        document.execCommand('copy');
+        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();
+    };
+}

package/dist/finite-state-machine.svelte.d.ts

@@ -0,0 +1,53 @@
+export type EventMap = Record<string, unknown[]>;
+type EventArgs<EventsT extends EventMap> = {
+    [K in keyof EventsT]: {
+        event: K;
+        args: EventsT[K];
+    };
+}[keyof EventsT];
+export type ActionMeta<StatesT extends string, EventsT extends EventMap, ContextT, CurrentT extends StatesT, K extends keyof EventsT> = {
+    from: CurrentT;
+    event: K;
+    args: EventsT[K];
+    context: ContextT;
+};
+export type EnterMeta<StatesT extends string, EventsT extends EventMap, ContextT, CurrentT extends StatesT> = {
+    to: CurrentT;
+    context: ContextT;
+} & (({
+    from: StatesT;
+} & EventArgs<EventsT>) | {
+    from: null;
+    event: null;
+    args: [];
+});
+export type ExitMeta<StatesT extends string, EventsT extends EventMap, ContextT, CurrentT extends StatesT> = {
+    from: CurrentT;
+    to: StatesT;
+    context: ContextT;
+} & EventArgs<EventsT>;
+export type Action<StatesT extends string, EventsT extends EventMap, ContextT, CurrentT extends StatesT, K extends keyof EventsT> = StatesT | ((meta: ActionMeta<StatesT, EventsT, ContextT, CurrentT, K>) => StatesT | void);
+export type StateHandler<StatesT extends string, EventsT extends EventMap, ContextT, CurrentT extends StatesT> = {
+    [K in keyof EventsT]?: Action<StatesT, EventsT, ContextT, CurrentT, K>;
+} & {
+    _enter?: (meta: EnterMeta<StatesT, EventsT, ContextT, CurrentT>) => void;
+    _exit?: (meta: ExitMeta<StatesT, EventsT, ContextT, CurrentT>) => void;
+};
+export type Transition<StatesT extends string, EventsT extends EventMap, ContextT = undefined> = {
+    [S in StatesT]: StateHandler<StatesT, EventsT, ContextT, S>;
+} & {
+    '*'?: StateHandler<StatesT, EventsT, ContextT, StatesT>;
+};
+export declare class FiniteStateMachine<StatesT extends string, EventsT extends EventMap, ContextT = undefined> {
+    #private;
+    readonly states: Transition<StatesT, EventsT, ContextT>;
+    constructor(initial: StatesT, states: Transition<StatesT, EventsT, ContextT>, ...options: undefined extends ContextT ? [] : [{
+        context: ContextT;
+    }]);
+    send: <K extends keyof EventsT>(event: K, ...args: EventsT[K]) => StatesT;
+    debounce: <K extends keyof EventsT>(event: K, wait?: number, ...args: EventsT[K]) => Promise<StatesT>;
+    get current(): StatesT;
+    get context(): ContextT;
+    set context(next: ContextT);
+}
+export {};

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

@@ -0,0 +1,78 @@
+import { DEV } from 'esm-env';
+export class FiniteStateMachine {
+    #current = $state();
+    #context = $state();
+    states;
+    constructor(initial, states, ...options) {
+        this.#current = initial;
+        this.states = states;
+        this.#context = options[0]?.context;
+        this.#lifecycle('_enter', initial, {
+            from: null,
+            to: initial,
+            event: null,
+            args: [],
+            context: this.#context
+        });
+    }
+    send = (event, ...args) => {
+        const action = this.states[this.#current]?.[event] ?? this.states['*']?.[event];
+        if (action === undefined) {
+            if (DEV) {
+                console.warn(`kenspeckle: unhandled event '${String(event)}' in state '${this.#current}'`);
+            }
+            return this.#current;
+        }
+        const target = typeof action === 'function'
+            ? action({
+                from: this.#current,
+                event,
+                args,
+                context: this.#context
+            })
+            : action;
+        if (target != null)
+            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
+            };
+        });
+    };
+    #transition(to, event, args) {
+        const from = this.#current;
+        this.#lifecycle('_exit', from, { from, to, event, args, context: this.#context });
+        if (this.#current !== from)
+            return; // _exit sent elsewhere; that transition supersedes
+        this.#current = to;
+        this.#lifecycle('_enter', to, { from, to, event, args, context: this.#context });
+    }
+    #lifecycle(kind, state, meta) {
+        const fn = this.states[state]?.[kind] ?? this.states['*']?.[kind];
+        fn?.(meta);
+    }
+    get current() {
+        return this.#current;
+    }
+    get context() {
+        return this.#context;
+    }
+    set context(next) {
+        this.#context = next;
+    }
+}

package/dist/index.d.ts

@@ -1 +1,6 @@
-export {};
+export { copy, copyText } from './copy.js';
+export type { CopyOptions, CopyText } from './copy.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 { viewTransition } from './view-transition.js';
+export type { StartViewTransition, ViewTransitionOptions, ViewTransitionUpdate } from './view-transition.js';

package/dist/index.js

@@ -1,2 +1,3 @@
-"use strict";
-// Reexport your entry components here
+export { copy, copyText } from './copy.js';
+export { FiniteStateMachine } from './finite-state-machine.svelte.js';
+export { viewTransition } from './view-transition.js';

package/dist/kit/index.d.ts

@@ -0,0 +1,5 @@
+export { retreat, viewTransition } from './view-transition.js';
+export type { NavigationTransitionOptions } from './view-transition.js';
+export { viewTransitionName } from './view-transition-name.js';
+export type { ViewTransitionNameOptions } from './view-transition-name.js';
+export type { Navigation } from './types.js';

package/dist/kit/index.js

@@ -0,0 +1,2 @@
+export { retreat, viewTransition } from './view-transition.js';
+export { viewTransitionName } from './view-transition-name.js';

package/dist/kit/types.d.ts

@@ -0,0 +1,12 @@
+/** Structural, not imported from Kit — any router handing over a completion promise fits. */
+export interface Navigation {
+    complete: Promise<void>;
+    type?: string;
+    delta?: number | null;
+    from?: {
+        url: URL;
+    } | null;
+    to?: {
+        url: URL;
+    } | null;
+}

package/dist/kit/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+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. */
+    when?: (navigation: Navigation) => boolean;
+    /** Claim inside the update callback instead, for an element that mounts during the transition. */
+    onArrival?: boolean;
+}
+type Phase = 'capture' | 'arrival';
+/** @internal — driven by the navigation registration. */
+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 {};

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

@@ -0,0 +1,48 @@
+const claims = new Set();
+let current = null;
+function wanted(claim, phase, navigation) {
+    if ((claim.options.onArrival ? 'arrival' : 'capture') !== phase)
+        return false;
+    return claim.options.when?.(navigation) ?? true;
+}
+function apply(claim) {
+    claim.element.style.viewTransitionName = claim.name;
+    claim.named = true;
+}
+function release(claim) {
+    if (!claim.named)
+        return;
+    claim.element.style.viewTransitionName = '';
+    claim.named = false;
+}
+/** @internal — driven by the navigation registration. */
+export function beginPhase(navigation, phase) {
+    current = { navigation, phase };
+    for (const claim of claims)
+        if (wanted(claim, phase, navigation))
+            apply(claim);
+}
+/** @internal */
+export function endTransition() {
+    current = null;
+    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(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/kit/view-transition.d.ts

@@ -0,0 +1,18 @@
+import { type ViewTransitionOptions, type ViewTransitionUpdate } from '../view-transition.js';
+import type { Navigation } from './types.js';
+export interface NavigationTransitionOptions extends Omit<ViewTransitionOptions, 'retreat' | 'onStart'> {
+    onStart?: (navigation: Navigation) => void;
+}
+/**
+ * A predicate, never a flag: Kit skips `beforeNavigate` for a navigation begun while another is in
+ * flight, so a flag set at click time can be stranded and reverse a later navigation.
+ *
+ * Returns a disposer shaped for `$effect` cleanup.
+ */
+export declare function retreat(next: (navigation: Navigation) => boolean): () => void;
+/** @internal */
+export declare function isRetreat(navigation: Navigation): boolean;
+/** @internal — the handler `viewTransition()` registers, exported so it is testable without a component. */
+export declare function navigationTransition({ onStart, onSettle, ...rest }?: NavigationTransitionOptions): (navigation: Navigation) => Promise<void>;
+export declare function viewTransition(options?: NavigationTransitionOptions): void;
+export declare function viewTransition(update: ViewTransitionUpdate, options?: ViewTransitionOptions): ViewTransition | undefined;

package/dist/kit/view-transition.js

@@ -0,0 +1,57 @@
+import { onNavigate } from '$app/navigation';
+import { runViewTransition, viewTransition as directTransition } from '../view-transition.js';
+import { beginPhase, endTransition } from './view-transition-name.js';
+const forward = () => false;
+let predicate = forward;
+/**
+ * A predicate, never a flag: Kit skips `beforeNavigate` for a navigation begun while another is in
+ * flight, so a flag set at click time can be stranded and reverse a later navigation.
+ *
+ * Returns a disposer shaped for `$effect` cleanup.
+ */
+export function retreat(next) {
+    predicate = next;
+    return () => {
+        // Identity-guarded: a stale disposer must not unregister whoever replaced it.
+        if (predicate === next)
+            predicate = forward;
+    };
+}
+/** @internal */
+export function isRetreat(navigation) {
+    // Kit sets delta only on a popstate: negative is Back, positive Forward. Absent, assume Back.
+    const back = navigation.type === 'popstate' && (navigation.delta ?? -1) < 0;
+    return back || predicate(navigation);
+}
+/** @internal — the handler `viewTransition()` registers, exported so it is testable without a component. */
+export function navigationTransition({ onStart, onSettle, ...rest } = {}) {
+    return (navigation) => new Promise((resolve) => {
+        let transitioning = false;
+        runViewTransition(async () => {
+            // resolve() BEFORE awaiting breaks a mutual wait: Kit holds the navigation until this
+            // promise settles, the browser holds the snapshot until the callback settles.
+            resolve();
+            await navigation.complete;
+            if (transitioning)
+                beginPhase(navigation, 'arrival');
+        }, {
+            ...rest,
+            state: isRetreat(navigation) ? 'retreat' : 'forward',
+            onStart: () => {
+                transitioning = true;
+                beginPhase(navigation, 'capture');
+                onStart?.(navigation);
+            },
+            onSettle: () => {
+                transitioning = false;
+                endTransition();
+                onSettle?.();
+            }
+        });
+    });
+}
+export function viewTransition(first, second) {
+    if (typeof first === 'function')
+        return directTransition(first, second);
+    onNavigate(navigationTransition(first));
+}

package/dist/view-transition.d.ts

@@ -0,0 +1,22 @@
+export type StartViewTransition = (update: () => void | Promise<void>) => ViewTransition;
+/** A union of signatures, not `() => void | Promise<void>`: TS's void-return relaxation applies per
+ *  member, so only this shape accepts a concise arrow like `() => (count += 1)`. */
+export type ViewTransitionUpdate = (() => void) | (() => Promise<void>);
+export interface ViewTransitionOptions {
+    /** Reverse direction — writes `step-retreat` instead of `step-forward`. */
+    retreat?: boolean;
+    /** Past this a crossfade reads as a hang: the update callback suspends rendering until it settles. */
+    deadline?: number;
+    onStart?: () => void;
+    onSettle?: () => void;
+    reducedMotion?: () => boolean;
+    /** Injected in tests; keeps the `bind` internal and init SSR-safe. */
+    start?: StartViewTransition;
+}
+/** @internal — `/kit` supplies its own attribute vocabulary. Not re-exported from the barrel. */
+export interface RunOptions extends ViewTransitionOptions {
+    state?: string;
+}
+export declare function viewTransition(update: ViewTransitionUpdate, options?: ViewTransitionOptions): ViewTransition | undefined;
+/** @internal */
+export declare function runViewTransition(update: ViewTransitionUpdate, { deadline, onStart, onSettle, reducedMotion, start, state }?: RunOptions): ViewTransition | undefined;

package/dist/view-transition.js

@@ -0,0 +1,58 @@
+import { settled } from 'svelte';
+import { prefersReducedMotion } from 'svelte/motion';
+const ignore = () => { };
+const root = () => document.documentElement;
+// A consumer throw must not strand the transition, so it goes to the page's error handling instead.
+const guard = (callback) => {
+    try {
+        callback?.();
+    }
+    catch (error) {
+        reportError(error);
+    }
+};
+// One transition per document: starting a second skips the first, whose `finished` then settles.
+let active;
+export function viewTransition(update, options = {}) {
+    return runViewTransition(update, {
+        ...options,
+        state: options.retreat ? 'step-retreat' : 'step-forward'
+    });
+}
+/** @internal */
+export function runViewTransition(update, { deadline = 600, onStart, onSettle, reducedMotion = () => prefersReducedMotion.current, start, state = 'step-forward' } = {}) {
+    // Resolved per call, never at module scope: SSR must not touch document.
+    const startTransition = start ??
+        (typeof document === 'undefined' ? undefined : document.startViewTransition?.bind(document));
+    // No transition at all, not merely no animation — the update callback suspends rendering.
+    if (!startTransition || reducedMotion()) {
+        // A sync throw still propagates; an async rejection is swallowed as the transition path swallows `finished`.
+        void Promise.resolve(update()).catch(ignore);
+        return;
+    }
+    root().dataset.viewTransition = state;
+    guard(onStart);
+    // `settled()`, not `tick()`: the browser snapshots the moment this callback resolves, and an async
+    // component's commit is batched — `tick()` only flushes synchronous updates and passes by luck.
+    const transition = startTransition(async () => {
+        await update();
+        await settled();
+    });
+    // Synchronously, before any microtask: a superseded predecessor settles one tick later.
+    active = transition;
+    const timer = setTimeout(() => transition.skipTransition(), deadline);
+    // Disarmed on the update callback, not `finished`: armed through the animation it snaps a running morph.
+    void transition.updateCallbackDone.catch(ignore).finally(() => clearTimeout(timer));
+    // Swallowed so cleanup still runs when the update callback threw; a skip fulfils `finished`.
+    void transition.finished.catch(ignore).finally(() => {
+        // Superseded: the successor owns the state and the claimed names, so its cleanup is not ours to run.
+        if (active !== transition)
+            return;
+        active = undefined;
+        delete root().dataset.viewTransition;
+        guard(onSettle);
+    });
+    // A skip rejects `ready`; unhandled, Chrome logs AbortError on the slow navigations the deadline rescues.
+    void transition.ready.catch(ignore);
+    return transition;
+}

package/package.json

@@ -1,6 +1,15 @@
 {
 	"name": "kenspeckle",
-	"version": "0.0.1",
+	"version": "0.1.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>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/brandonpittman/kenspeckle.git"
+	},
+	"homepage": "https://github.com/brandonpittman/kenspeckle#readme",
+	"bugs": "https://github.com/brandonpittman/kenspeckle/issues",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "wrangler types --check && vite build && npm run prepack",
@@ -19,7 +28,8 @@
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"!dist/vitest-examples"
 	],
 	"sideEffects": [
 		"**/*.css"
@@ -30,11 +40,23 @@
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
-			"svelte": "./dist/index.js"
+			"svelte": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./kit": {
+			"types": "./dist/kit/index.d.ts",
+			"svelte": "./dist/kit/index.js",
+			"default": "./dist/kit/index.js"
 		}
 	},
 	"peerDependencies": {
-		"svelte": "^5.0.0"
+		"svelte": "^5.40.0",
+		"@sveltejs/kit": "^2.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@sveltejs/kit": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
@@ -64,6 +86,16 @@
 		"wrangler": "^4.97.0"
 	},
 	"keywords": [
-		"svelte"
-	]
+		"svelte",
+		"svelte5",
+		"sveltekit",
+		"runes",
+		"attachments",
+		"view-transitions",
+		"state-machine",
+		"utilities"
+	],
+	"dependencies": {
+		"esm-env": "^1.2.2"
+	}
 }

package/dist/vitest-examples/Welcome.svelte

@@ -1,8 +0,0 @@
-<script>
-	import { greet } from './greet';
-
-	let { host = 'SvelteKit', guest = 'Vitest' } = $props();
-</script>
-
-<h1>{greet(host)}</h1>
-<p>{greet(guest)}</p>

package/dist/vitest-examples/Welcome.svelte.d.ts

@@ -1,13 +0,0 @@
-export default Welcome;
-type Welcome = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<$$ComponentProps>): void;
-};
-declare const Welcome: import("svelte").Component<{
-    host?: string;
-    guest?: string;
-}, {}, "">;
-type $$ComponentProps = {
-    host?: string;
-    guest?: string;
-};

package/dist/vitest-examples/greet.d.ts

@@ -1 +0,0 @@
-export declare function greet(name: string): string;

package/dist/vitest-examples/greet.js

@@ -1,3 +0,0 @@
-export function greet(name) {
-    return 'Hello, ' + name + '!';
-}