hono-preact 0.1.0 → 0.3.0

package/dist/iso/internal/page-middleware-host.js

@@ -0,0 +1,119 @@
+import { Fragment as _Fragment, jsx as _jsx } from "preact/jsx-runtime";
+import { useLocation } from 'preact-iso';
+import { Suspense } from 'preact/compat';
+import { useContext, useEffect, useRef } from 'preact/hooks';
+import { isBrowser } from '../is-browser.js';
+import { isRedirect, isRender } from '../outcomes.js';
+import { dispatchServer, dispatchClient } from './middleware-runner.js';
+import { partitionUse } from './use-partitioner.js';
+import wrapPromise from './wrap-promise.js';
+import { HonoRequestContext } from './contexts.js';
+function startChain(use, location, honoCtx) {
+    const { middleware } = partitionUse(use);
+    if (isBrowser()) {
+        const client = middleware.filter((m) => m.runs === 'client');
+        if (client.length === 0)
+            return Promise.resolve({ outcome: undefined });
+        return dispatchClient({
+            middleware: client,
+            ctx: { scope: 'page', location },
+            inner: async () => undefined,
+        }).then((r) => r.kind === 'outcome' ? { outcome: r.outcome } : { outcome: undefined });
+    }
+    const server = middleware.filter((m) => m.runs === 'server');
+    if (server.length === 0)
+        return Promise.resolve({ outcome: undefined });
+    if (!honoCtx) {
+        // Reject (don't throw synchronously). `wrapPromise` consumes a Promise;
+        // a sync throw here never reaches it, so the Suspense/ErrorBoundary path
+        // ends up surfacing a coerced "[object Object]"-style message instead of
+        // this explicit one. Returning a rejected promise routes the message
+        // through `wrapPromise.read()` -> the boundary's error state correctly.
+        return Promise.reject(new Error('<PageMiddlewareHost> rendered server-side without a HonoContext.Provider. ' +
+            'renderPage must wrap the prerendered tree in <HonoContext.Provider value={{ context: c }}>.'));
+    }
+    return dispatchServer({
+        middleware: server,
+        ctx: {
+            scope: 'page',
+            c: honoCtx,
+            signal: (honoCtx.req?.raw?.signal ??
+                new AbortController().signal),
+            location,
+        },
+        inner: async () => undefined,
+    }).then((r) => r.kind === 'outcome' ? { outcome: r.outcome } : { outcome: undefined });
+}
+function HostConsumer({ resultRef, children, }) {
+    // resultRef.current is populated by the parent before this consumer
+    // renders; the null branch is just a type-narrow guard.
+    const wrapped = resultRef.current;
+    const { outcome } = wrapped ? wrapped.read() : { outcome: undefined };
+    const { route } = useLocation();
+    // Client-side redirect: navigate in an effect rather than during render.
+    // Render-time side effects are forbidden by Suspense semantics; doing
+    // route() in render would also fire on every Preact re-entry during
+    // suspension resume. Keyed on the resolved target so a fresh outcome
+    // for the same path doesn't refire (the outcome is cached per chain,
+    // so this only changes when the path itself changes and a new chain
+    // produces a redirect to a different target).
+    const redirectTo = isRedirect(outcome) && isBrowser() ? outcome.to : null;
+    useEffect(() => {
+        if (redirectTo !== null)
+            route(redirectTo);
+        // `route` is intentionally omitted from deps: it comes from
+        // useLocation() which is stable per LocationProvider mount, and
+        // referencing it here would re-fire the effect on every render the
+        // provider produces.
+    }, [redirectTo]);
+    if (outcome === undefined) {
+        return _jsx(_Fragment, { children: children });
+    }
+    if (isRedirect(outcome)) {
+        if (isBrowser()) {
+            // Effect above will schedule the navigation; render nothing in the
+            // meantime so the old tree doesn't briefly flash.
+            return null;
+        }
+        // Server: rethrow so renderPage's outer handler can translate to HTTP redirect.
+        throw outcome;
+    }
+    if (isRender(outcome)) {
+        const Alt = outcome.Component;
+        // Equality-by-reference semantics: each `render(Component)` call
+        // returns a fresh outcome object, but the wrapped chain caches its
+        // result for the lifetime of a path. Within the same path render
+        // outcomes are stable. Across paths, the `resultRef` is rewrapped
+        // (see PageMiddlewareHost below), so a fresh chain produces a fresh
+        // outcome and Preact remounts naturally when `Alt` differs. If a
+        // middleware returns the SAME component reference across paths,
+        // Preact treats it as the same element and preserves state. That's
+        // the documented semantic; if callers need a forced remount, they
+        // can wrap the returned component or vary props.
+        return _jsx(Alt, {});
+    }
+    // Deny on the page-render path: rethrow so the outer error boundary or
+    // handler can translate to the right response.
+    throw outcome;
+}
+export const PageMiddlewareHost = ({ use = [], location, fallback, children }) => {
+    const honoCtx = useContext(HonoRequestContext).context;
+    // Lazy ref pattern. `useRef(null)` serves a dual purpose: it's the
+    // "not-yet-computed" sentinel AND the persistent slot for the wrapped
+    // chain result. We compute on first render and on subsequent renders
+    // ONLY when the path changed. `useRef(wrapPromise(startChain(...)))`
+    // would evaluate `startChain` every render before useRef decided whether
+    // to keep it, which synchronously fires `dispatchServer`/`dispatchClient`
+    // every render. That's O(renders) middleware invocations instead of
+    // O(navigations); auth checks, analytics, redirects would all repeat.
+    const resultRef = useRef(null);
+    const prevPath = useRef(location.path);
+    if (resultRef.current === null) {
+        resultRef.current = wrapPromise(startChain(use, location, honoCtx));
+    }
+    else if (prevPath.current !== location.path) {
+        prevPath.current = location.path;
+        resultRef.current = wrapPromise(startChain(use, location, honoCtx));
+    }
+    return (_jsx(Suspense, { fallback: fallback, children: _jsx(HostConsumer, { resultRef: resultRef, children: children }) }));
+};

package/dist/iso/internal/route-boundary.d.ts

@@ -1,6 +1,6 @@
 import { Component } from 'preact';
-import type { ComponentChildren, FunctionComponent, JSX } from 'preact';
-type ErrorFallback = JSX.Element | ((error: Error, reset: () => void) => JSX.Element);
+import type { ComponentChildren, FunctionComponent } from 'preact';
+type ErrorFallback = ComponentChildren | ((error: Error, reset: () => void) => ComponentChildren);
 type ErrorBoundaryProps = {
     fallback?: ErrorFallback;
     children: ComponentChildren;
@@ -14,11 +14,12 @@ export declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
     static getDerivedStateFromError(error: unknown): {
         error: Error;
     };
+    componentDidCatch(error: unknown): void;
     reset: () => void;
-    render(): ComponentChildren;
+    render(): any;
 }
 export declare const RouteBoundary: FunctionComponent<{
-    fallback?: JSX.Element;
+    fallback?: ComponentChildren;
     errorFallback?: ErrorFallback;
     children: ComponentChildren;
 }>;

package/dist/iso/internal/route-boundary.js

@@ -1,11 +1,27 @@
 import { jsx as _jsx } from "preact/jsx-runtime";
 import { Component } from 'preact';
 import { Suspense } from 'preact/compat';
+import { isOutcome } from '../outcomes.js';
 export class ErrorBoundary extends Component {
     state = { error: null };
+    // Outcomes (redirect/deny/render) are NOT errors; they are control-flow
+    // signals that the dispatcher / renderPage outer catch is responsible for
+    // translating. If RouteBoundary swallowed them here, every page-scope
+    // throw from `PageMiddlewareHost` (HostConsumer rethrowing a deny on SSR,
+    // for example) would be coerced into `new Error(String(outcome))` and
+    // surfaced as the fallback UI, with no 302 / 403 / etc. reaching the
+    // network. Re-throw outcomes so the outer handler sees them. The same
+    // guard lives in `componentDidCatch` because Preact invokes both hooks
+    // when the boundary catches; whichever fires first must not swallow.
     static getDerivedStateFromError(error) {
+        if (isOutcome(error))
+            throw error;
         return { error: error instanceof Error ? error : new Error(String(error)) };
     }
+    componentDidCatch(error) {
+        if (isOutcome(error))
+            throw error;
+    }
     reset = () => {
         this.setState({ error: null });
     };

package/dist/iso/internal/safe-redirect.d.ts

@@ -0,0 +1,7 @@
+export declare function isSameOrigin(target: string): boolean;
+/**
+ * Navigate to `target` only when it resolves same-origin against the current
+ * window. Cross-origin targets log a console error and are not followed.
+ * Returns true when the navigation was issued.
+ */
+export declare function assignSafeRedirect(target: string): boolean;

package/dist/iso/internal/safe-redirect.js

@@ -0,0 +1,27 @@
+export function isSameOrigin(target) {
+    if (typeof window === 'undefined')
+        return true;
+    try {
+        // Relative URLs resolve against the current origin and are always same-origin.
+        const resolved = new URL(target, window.location.href);
+        return resolved.origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Navigate to `target` only when it resolves same-origin against the current
+ * window. Cross-origin targets log a console error and are not followed.
+ * Returns true when the navigation was issued.
+ */
+export function assignSafeRedirect(target) {
+    if (typeof window === 'undefined')
+        return false;
+    if (!isSameOrigin(target)) {
+        console.error(`[hono-preact] refusing to navigate to cross-origin redirect target: ${target}`);
+        return false;
+    }
+    window.location.assign(target);
+    return true;
+}

package/dist/iso/internal/sse-decoder.d.ts

@@ -2,4 +2,4 @@ export type SSEEvent = {
     event: string;
     data: string;
 };
-export declare function readSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEEvent, void, unknown>;
+export declare function readSSE(stream: ReadableStream<BufferSource>): AsyncGenerator<SSEEvent, void, unknown>;

package/dist/iso/internal/sse-decoder.js

@@ -1,39 +1,53 @@
-export async function* readSSE(stream) {
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
+function lineSplitTransform() {
     let buffer = '';
+    return new TransformStream({
+        transform(chunk, controller) {
+            buffer += chunk;
+            let nl;
+            while ((nl = buffer.indexOf('\n')) !== -1) {
+                controller.enqueue(buffer.slice(0, nl).replace(/\r$/, ''));
+                buffer = buffer.slice(nl + 1);
+            }
+        },
+        flush(controller) {
+            if (buffer.length) {
+                controller.enqueue(buffer.replace(/\r$/, ''));
+                buffer = '';
+            }
+        },
+    });
+}
+export async function* readSSE(stream) {
+    const lines = stream
+        .pipeThrough(new TextDecoderStream())
+        .pipeThrough(lineSplitTransform());
     let event = 'message';
     let dataLines = [];
+    const reader = lines.getReader();
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value: line } = await reader.read();
             if (done) {
-                buffer += decoder.decode();
-                if (dataLines.length)
+                if (dataLines.length) {
                     yield { event, data: dataLines.join('\n') };
+                }
                 return;
             }
-            buffer += decoder.decode(value, { stream: true });
-            let nl;
-            while ((nl = buffer.indexOf('\n')) !== -1) {
-                const line = buffer.slice(0, nl).replace(/\r$/, '');
-                buffer = buffer.slice(nl + 1);
-                if (line === '') {
-                    if (dataLines.length) {
-                        yield { event, data: dataLines.join('\n') };
-                    }
-                    event = 'message';
-                    dataLines = [];
-                }
-                else if (line.startsWith(':')) {
-                    // SSE comment / keepalive, ignore
-                }
-                else if (line.startsWith('event:')) {
-                    event = line.slice(6).trim();
-                }
-                else if (line.startsWith('data:')) {
-                    dataLines.push(line.slice(5).replace(/^ /, ''));
+            if (line === '') {
+                if (dataLines.length) {
+                    yield { event, data: dataLines.join('\n') };
                 }
+                event = 'message';
+                dataLines = [];
+            }
+            else if (line.startsWith(':')) {
+                // SSE comment / keepalive, ignore
+            }
+            else if (line.startsWith('event:')) {
+                event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                dataLines.push(line.slice(5).replace(/^ /, ''));
             }
         }
     }

package/dist/iso/internal/stream-observer-runner.d.ts

@@ -0,0 +1,13 @@
+import type { StreamObserver, ServerStreamCtx } from '../define-stream-observer.js';
+export declare function fanStart(observers: ReadonlyArray<StreamObserver<unknown, never>>, ctx: ServerStreamCtx): void;
+export declare function fanChunk(observers: ReadonlyArray<StreamObserver<unknown, never>>, ctx: ServerStreamCtx, chunk: unknown, index: number): void;
+export declare function fanEnd(observers: ReadonlyArray<StreamObserver<unknown, never>>, ctx: ServerStreamCtx, info: {
+    chunks: number;
+    result: unknown;
+}): void;
+export declare function fanError(observers: ReadonlyArray<StreamObserver<unknown, never>>, ctx: ServerStreamCtx, err: unknown, info: {
+    chunks: number;
+}): void;
+export declare function fanAbort(observers: ReadonlyArray<StreamObserver<unknown, never>>, ctx: ServerStreamCtx, info: {
+    chunks: number;
+}): void;

package/dist/iso/internal/stream-observer-runner.js

@@ -0,0 +1,48 @@
+function safeCall(fn) {
+    if (!fn)
+        return;
+    try {
+        fn();
+    }
+    catch (err) {
+        // Observer errors are isolated: surface via console for visibility but do
+        // not propagate. The stream is the source of truth; observers are a side
+        // channel and cannot corrupt the channel they observe.
+        // eslint-disable-next-line no-console
+        console.error('[stream-observer] hook threw and was isolated:', err);
+    }
+}
+export function fanStart(observers, ctx) {
+    for (const o of observers) {
+        safeCall(o.onStart ? () => o.onStart(ctx) : undefined);
+    }
+}
+export function fanChunk(observers, ctx, chunk, index) {
+    for (const o of observers) {
+        safeCall(o.onChunk ? () => o.onChunk(ctx, chunk, index) : undefined);
+    }
+}
+export function fanEnd(observers, ctx, info) {
+    for (const o of observers) {
+        safeCall(o.onEnd
+            ? () => 
+            // The partitioner widens observers to TResult=never (the only
+            // shape that admits arbitrary user-declared TResult); the call
+            // site provides whatever the underlying stream produced. The
+            // cast bridges the invariance gap and is safe because TS
+            // can't reason about the contravariant function-parameter
+            // shape across the array boundary.
+            o.onEnd(ctx, info)
+            : undefined);
+    }
+}
+export function fanError(observers, ctx, err, info) {
+    for (const o of observers) {
+        safeCall(o.onError ? () => o.onError(ctx, err, info) : undefined);
+    }
+}
+export function fanAbort(observers, ctx, info) {
+    for (const o of observers) {
+        safeCall(o.onAbort ? () => o.onAbort(ctx, info) : undefined);
+    }
+}

package/dist/iso/internal/use-partitioner.d.ts

@@ -0,0 +1,9 @@
+import type { Middleware } from '../define-middleware.js';
+import type { StreamObserver } from '../define-stream-observer.js';
+type AnyObserver = StreamObserver<unknown, never>;
+type UseEntry = Middleware | AnyObserver;
+export declare function partitionUse(use: ReadonlyArray<UseEntry>): {
+    middleware: Middleware[];
+    observers: AnyObserver[];
+};
+export {};

package/dist/iso/internal/use-partitioner.js

@@ -0,0 +1,11 @@
+export function partitionUse(use) {
+    const middleware = [];
+    const observers = [];
+    for (const entry of use) {
+        if (entry.__kind === 'middleware')
+            middleware.push(entry);
+        else
+            observers.push(entry);
+    }
+    return { middleware, observers };
+}

package/dist/iso/internal/use-types.d.ts

@@ -0,0 +1,7 @@
+import type { ServerMiddleware, ClientMiddleware, Scope } from '../define-middleware.js';
+import type { StreamObserver } from '../define-stream-observer.js';
+export type Use<S extends Scope, Streaming extends boolean, T = unknown, R = void> = ReadonlyArray<ServerMiddleware<S> | (S extends 'page' ? ClientMiddleware : never) | (Streaming extends true ? StreamObserver<T, R> : never)>;
+export type PageUse = ReadonlyArray<ServerMiddleware<'page'> | ClientMiddleware | StreamObserver<unknown, never>>;
+export type AppUse = PageUse;
+export type LoaderUse<T, Streaming extends boolean> = Use<'loader', Streaming, T, void>;
+export type ActionUse<TChunk, TResult, Streaming extends boolean> = Use<'action', Streaming, TChunk, TResult>;

package/dist/iso/internal/use-types.js

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

package/dist/iso/internal.d.ts

@@ -1,19 +1,26 @@
 export { Loader } from './internal/loader.js';
 export { Envelope } from './internal/envelope.js';
 export { RouteBoundary } from './internal/route-boundary.js';
-export { Guards, GuardGate, useGuardResult } from './internal/guards.js';
 export { OptimisticOverlay } from './internal/optimistic-overlay.js';
-export { LoaderIdContext, LoaderDataContext, GuardResultContext, } from './internal/contexts.js';
+export { serializeActionOutcome, type ActionEnvelope, type ActionResolution, type SerializedEnvelope, } from './internal/action-envelope.js';
+export { LoaderIdContext, LoaderDataContext } from './internal/contexts.js';
 export { ReloadContext } from './reload-context.js';
 export { RouteLocationsContext, RouteLocationsProvider, } from './internal/route-locations.js';
 export { getPreloadedData, deletePreloadedData } from './internal/preload.js';
-export { runRequestScope, getRequestStore, captureRequestScope, } from './cache.js';
+export { runRequestScope, getRequestStore, captureRequestScope, getActionResultSlot, setActionResultSlot, type ActionResultSlot, } from './cache.js';
 export { default as wrapPromise } from './internal/wrap-promise.js';
-export { runServerGuards, runClientGuards } from './guard.js';
 export { HonoRequestContext } from './internal/contexts.js';
+export { PageMiddlewareHost } from './internal/page-middleware-host.js';
 export { __dispatchRouteChange, __subscribeRouteChange, } from './internal/route-change.js';
 export { installStreamRegistry, subscribeToLoaderStream, } from './internal/stream-registry.js';
 export { registerServerStreamingLoader, takeServerStreamingLoaders, } from './internal/streaming-ssr.js';
 export type { ServerLoaderStream } from './internal/streaming-ssr.js';
+export { beginSubmit, endSubmit, isPending, subscribe as subscribeFormSubmit, } from './internal/form-submit-store.js';
+export { assignSafeRedirect, isSameOrigin } from './internal/safe-redirect.js';
+export { setLastActionResult, clearLastActionResult, getLastActionResult, subscribeActionResults, type StoredActionResult, } from './internal/action-result-store.js';
+export { dispatchServer, dispatchClient, type DispatchResult, } from './internal/middleware-runner.js';
+export { partitionUse } from './internal/use-partitioner.js';
+export { fanStart, fanChunk, fanEnd, fanError, fanAbort, } from './internal/stream-observer-runner.js';
 export { __$createLoaderStub_hpiso } from './internal/loader-stub.js';
-export { __$guardNoop_hpiso } from './internal/guard-noop.js';
+export { readSSE } from './internal/sse-decoder.js';
+export type { SSEEvent } from './internal/sse-decoder.js';

package/dist/iso/internal.js

@@ -3,8 +3,8 @@
 // These primitives compose the default <Page> pipeline. They're kept
 // behind a subpath so the front door (@hono-preact/iso) stays small.
 // Use them when definePage bindings or <Page> props don't express
-// what you need (e.g. distinct fallbacks for guards vs. loader, custom
-// pipeline ordering, advanced SSR work).
+// what you need (e.g. custom middleware composition, distinct fallbacks
+// for the middleware host vs. the loader, advanced SSR work).
 //
 // STABILITY: this subpath is intentionally less stable than the package's
 // main surface. Symbols may be renamed, retyped, or removed in any
@@ -27,23 +27,32 @@
 export { Loader } from './internal/loader.js';
 export { Envelope } from './internal/envelope.js';
 export { RouteBoundary } from './internal/route-boundary.js';
-export { Guards, GuardGate, useGuardResult } from './internal/guards.js';
 export { OptimisticOverlay } from './internal/optimistic-overlay.js';
-export { LoaderIdContext, LoaderDataContext, GuardResultContext, } from './internal/contexts.js';
+export { serializeActionOutcome, } from './internal/action-envelope.js';
+export { LoaderIdContext, LoaderDataContext } from './internal/contexts.js';
 export { ReloadContext } from './reload-context.js';
 export { RouteLocationsContext, RouteLocationsProvider, } from './internal/route-locations.js';
 export { getPreloadedData, deletePreloadedData } from './internal/preload.js';
-export { runRequestScope, getRequestStore, captureRequestScope, } from './cache.js';
+export { runRequestScope, getRequestStore, captureRequestScope, getActionResultSlot, setActionResultSlot, } from './cache.js';
 export { default as wrapPromise } from './internal/wrap-promise.js';
-export { runServerGuards, runClientGuards } from './guard.js';
 export { HonoRequestContext } from './internal/contexts.js';
+export { PageMiddlewareHost } from './internal/page-middleware-host.js';
 export { __dispatchRouteChange, __subscribeRouteChange, } from './internal/route-change.js';
 export { installStreamRegistry, subscribeToLoaderStream, } from './internal/stream-registry.js';
 export { registerServerStreamingLoader, takeServerStreamingLoaders, } from './internal/streaming-ssr.js';
+export { beginSubmit, endSubmit, isPending, subscribe as subscribeFormSubmit, } from './internal/form-submit-store.js';
+export { assignSafeRedirect, isSameOrigin } from './internal/safe-redirect.js';
+export { setLastActionResult, clearLastActionResult, getLastActionResult, subscribeActionResults, } from './internal/action-result-store.js';
+// Middleware dispatcher + observer fanout. Internal-stability subpath.
+export { dispatchServer, dispatchClient, } from './internal/middleware-runner.js';
+export { partitionUse } from './internal/use-partitioner.js';
+export { fanStart, fanChunk, fanEnd, fanError, fanAbort, } from './internal/stream-observer-runner.js';
 // ─── Section 2: framework-emitted (DO NOT IMPORT FROM USER CODE) ─────────
 // The `__$..._hpiso` naming makes the convention visible at every grep:
 // these symbols are referenced by code the framework's Vite plugins emit
 // (serverOnlyPlugin's loader stubs, guardStripPlugin's no-op replacement).
 // User code that imports them couples to plugin internals.
 export { __$createLoaderStub_hpiso } from './internal/loader-stub.js';
-export { __$guardNoop_hpiso } from './internal/guard-noop.js';
+// SSE decoder; useful in tests and advanced consumers that need to read
+// a streaming loader/action response as a sequence of typed SSE events.
+export { readSSE } from './internal/sse-decoder.js';

package/dist/iso/optimistic-action.d.ts

@@ -1,14 +1,23 @@
 import { type UseActionOptions, type UseActionResult, type ActionStub } from './action.js';
+import { type OptimisticHandle } from './optimistic.js';
 import type { LoaderRef } from './define-loader.js';
+export declare const OPTIMISTIC_BRAND: unique symbol;
+export type OptimisticBinding<TPayload, TBase> = {
+    apply: (current: TBase, payload: TPayload) => TBase;
+    addOptimistic: (payload: TPayload) => OptimisticHandle;
+};
 export type UseOptimisticActionOptions<TPayload, TResult, TBase, TChunk = never> = Omit<UseActionOptions<TPayload, TResult, TChunk>, 'invalidate' | 'onMutate' | 'onError' | 'onSuccess'> & {
     base: TBase;
     apply: (current: TBase, payload: TPayload) => TBase;
     invalidate?: 'auto' | ReadonlyArray<LoaderRef<unknown>>;
     onSuccess?: (data: TResult) => void;
     onError?: (err: Error) => void;
+    /** Forwarded to the internal `useOptimistic` call. */
+    transition?: boolean;
 };
-export type UseOptimisticActionResult<TPayload, TResult, TBase> = UseActionResult<TPayload, TResult> & {
+export type UseOptimisticActionResult<TPayload, TResult, TBase> = ActionStub<TPayload, TResult, never> & UseActionResult<TPayload, TResult> & {
     value: TBase;
+    readonly [OPTIMISTIC_BRAND]: OptimisticBinding<TPayload, TBase>;
 };
 /**
  * Like `useAction`, but with an optimistic-update wrapper. `TChunk` defaults

package/dist/iso/optimistic-action.js

@@ -1,5 +1,6 @@
 import { useAction, } from './action.js';
 import { useOptimistic } from './optimistic.js';
+export const OPTIMISTIC_BRAND = Symbol('hono-preact.optimistic');
 /**
  * Like `useAction`, but with an optimistic-update wrapper. `TChunk` defaults
  * to `never` so existing non-streaming call sites are unaffected. Pass the
@@ -7,8 +8,8 @@ import { useOptimistic } from './optimistic.js';
  * when the action is streaming and you need a typed `onChunk` callback.
  */
 export function useOptimisticAction(stub, options) {
-    const { base, apply, onSuccess, onError, ...actionOpts } = options;
-    const [value, addOptimistic] = useOptimistic(base, apply);
+    const { base, apply, onSuccess, onError, transition, ...actionOpts } = options;
+    const [value, addOptimistic] = useOptimistic(base, apply, { transition });
     const action = useAction(stub, {
         ...actionOpts,
         onMutate: (payload) => addOptimistic(payload),
@@ -21,5 +22,12 @@ export function useOptimisticAction(stub, options) {
             onError?.(err);
         },
     });
-    return { ...action, value };
+    return {
+        __module: stub.__module,
+        __action: stub.__action,
+        useAction: stub.useAction,
+        ...action,
+        value,
+        [OPTIMISTIC_BRAND]: { apply, addOptimistic },
+    };
 }

package/dist/iso/optimistic.d.ts

@@ -2,4 +2,13 @@ export type OptimisticHandle = {
     settle: () => void;
     revert: () => void;
 };
-export declare function useOptimistic<TBase, TPayload>(base: TBase, reducer: (current: TBase, payload: TPayload) => TBase): [TBase, (payload: TPayload) => OptimisticHandle];
+export type UseOptimisticOptions = {
+    /**
+     * When true, the settle and revert paths are wrapped in
+     * `document.startViewTransition`. The initial optimistic update is never
+     * wrapped (it must paint same-frame). Falls back to a synchronous update
+     * when `document.startViewTransition` is unavailable.
+     */
+    transition?: boolean;
+};
+export declare function useOptimistic<TBase, TPayload>(base: TBase, reducer: (current: TBase, payload: TPayload) => TBase, options?: UseOptimisticOptions): [TBase, (payload: TPayload) => OptimisticHandle];

package/dist/iso/optimistic.js

@@ -1,14 +1,50 @@
 import { useCallback, useReducer, useRef } from 'preact/hooks';
-export function useOptimistic(base, reducer) {
+export function useOptimistic(base, reducer, options) {
     const queueRef = useRef([]);
     const lastBaseRef = useRef(base);
     const idRef = useRef(0);
     const [, forceRender] = useReducer((c) => c + 1, 0);
+    const transitionRef = useRef(options?.transition === true);
+    transitionRef.current = options?.transition === true;
     if (!Object.is(lastBaseRef.current, base)) {
         queueRef.current = queueRef.current.filter((e) => e.status !== 'ready');
         lastBaseRef.current = base;
     }
     const value = queueRef.current.reduce((acc, e) => reducer(acc, e.payload), base);
+    // Reads `transitionRef.current` at invocation time, not capture time, so it
+    // is safe to close over from the memoized `addOptimistic` (useCallback([]))
+    // below. Each render rebinds this function and writes the latest option
+    // value into the ref; settle/revert created by the stale memoized callback
+    // still see the up-to-date `transition` setting through the ref.
+    //
+    // The callback returns a promise that resolves on the next animation frame
+    // so the browser snapshots Preact's POST-render DOM as "new state". Without
+    // the rAF wait, `forceRender()` (an async dispatch through useReducer) has
+    // not yet flushed when `startViewTransition` snapshots, and the transition
+    // captures identical before/after frames with no visible animation.
+    const runWithTransition = (mutator) => {
+        if (transitionRef.current &&
+            typeof document !== 'undefined' &&
+            typeof document.startViewTransition === 'function') {
+            document.startViewTransition(async () => {
+                mutator();
+                await new Promise((resolve) => {
+                    if (typeof requestAnimationFrame === 'function') {
+                        requestAnimationFrame(() => resolve());
+                    }
+                    else {
+                        // Non-DOM environment (shouldn't reach this branch given the
+                        // outer check, but defensive). Resolve on next microtask so
+                        // Preact's scheduled render runs.
+                        queueMicrotask(resolve);
+                    }
+                });
+            });
+        }
+        else {
+            mutator();
+        }
+    };
     const addOptimistic = useCallback((payload) => {
         const id = ++idRef.current;
         queueRef.current = [...queueRef.current, { id, payload, status: 'active' }];
@@ -17,13 +53,17 @@ export function useOptimistic(base, reducer) {
             settle: () => {
                 const entry = queueRef.current.find((e) => e.id === id);
                 if (entry && entry.status === 'active') {
-                    entry.status = 'ready';
-                    forceRender();
+                    runWithTransition(() => {
+                        entry.status = 'ready';
+                        forceRender();
+                    });
                 }
             },
             revert: () => {
-                queueRef.current = queueRef.current.filter((e) => e.id !== id);
-                forceRender();
+                runWithTransition(() => {
+                    queueRef.current = queueRef.current.filter((e) => e.id !== id);
+                    forceRender();
+                });
             },
         };
     }, []);