@plutoframework/frontend 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pluto Framework contributors
+
+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,3 +1,198 @@
-# Temporary Holding Version
+# Pluto Frontend
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed frontend primitives for Pluto applications. Start with explicit UI state
+transitions and effects; subscribe from React when needed.
+
+```sh
+npm install @plutoframework/frontend
+```
+
+```ts
+import { createMachine } from "@plutoframework/frontend/state";
+import type { Decision } from "@plutoframework/frontend/state";
+import { useMachine } from "@plutoframework/frontend/react";
+```
+
+The state entrypoint has **zero runtime dependencies**. React is an optional peer;
+install React 18.3.1 or 19 separately when using the React entrypoint. This package
+is ESM-only and includes TypeScript declarations. The root import is intentionally
+absent: choose a specific primitive. No CSS, component library or Go runtime is
+required. Future frontend primitives can use additional entrypoints here.
+
+## Define a flow
+
+```ts
+import { createMachine } from "@plutoframework/frontend/state";
+import type { Decision } from "@plutoframework/frontend/state";
+
+type State = { readonly status: "idle" | "pending" | "done" };
+type Event = { readonly type: "start" | "done" };
+type Effect = { readonly type: "load" };
+
+function transition(current: State, event: Event): Decision<State, Effect> {
+  if (current.status === "idle" && event.type === "start") {
+    return {
+      accepted: true,
+      state: { status: "pending" },
+      effect: { type: "load" },
+    };
+  }
+
+  if (current.status === "pending" && event.type === "done") {
+    return { accepted: true, state: { status: "done" } };
+  }
+
+  return { accepted: false, state: current };
+}
+
+const flow = createMachine<State, Event, Effect>({
+  initial: { status: "idle" },
+  transition,
+  async execute(_effect, { signal, send }) {
+    const response = await fetch("/api/summary", { signal });
+    if (!response.ok) throw new Error("Summary request failed");
+    await send({ type: "done" });
+  },
+});
+
+// Commits pending synchronously, then awaits its effect. Handle errors explicitly.
+await flow.send({ type: "start" });
+```
+
+Use your feature's existing query/mutation adapter for real applications. The
+small fetch example demonstrates the boundary; it is not a new HTTP client.
+
+## Transition rules
+
+Transitions are pure application functions. They must neither perform I/O nor
+mutate state/events or call the controller. Return a new immutable snapshot for
+accepted changes. Rejected decisions preserve the controller's existing snapshot,
+even if the returned decision supplies a different state. TypeScript readonly
+fields are compile-time guidance; this library does not clone or freeze objects.
+
+An accepted decision may describe one effect. Missing executors are rejected
+before committing an effect-bearing decision. Effects execute outside rendering,
+reducers and subscription setup. States, events and guards remain ordinary typed
+application code, with no global registration, reflection, DSL or automatic I/O.
+
+## Controller lifecycle
+
+| Method                 | Behavior                                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `getSnapshot()`        | Returns the current stable snapshot                                                            |
+| `getInitialSnapshot()` | Returns the immutable initial snapshot for SSR                                                 |
+| `subscribe(listener)`  | Subscribes until the returned cleanup is called                                                |
+| `send(event)`          | Commits an accepted transition synchronously; resolves to acceptance after its effect finishes |
+| `reset()`              | Aborts executions, fences their callbacks and restores the initial snapshot                    |
+| `dispose()`            | Permanently aborts executions, removes subscribers and rejects further events                  |
+
+Always await or catch `send()` promises. Transition/executor/subscriber exceptions
+reject the sending promise. Transition errors do not commit; executor or subscriber
+errors after commit do not roll state back. Subscription callbacks must be small,
+synchronous and nonthrowing. Model expected request failures as typed events, as
+shown in [the purchase flow](https://github.com/plutoframework/pluto-frontend/blob/main/examples/purchases/approval.ts).
+
+Each effect receives an AbortSignal and a scoped `send`. That callback returns
+false after reset, disposal or executor completion, so late responses cannot
+update a replacement interaction. Cancellation is cooperative: an executor that
+ignores its signal can keep running, and its original sending promise can remain
+pending. There are no automatic retries, execution timeouts or concurrency limits.
+The transition function defines which events may start additional work.
+
+## React
+
+Pass an existing controller into your component:
+
+```tsx
+import type { Machine } from "@plutoframework/frontend/state";
+
+function Summary({
+  flow,
+  onError,
+}: {
+  flow: Machine<State, Event>;
+  onError: (error: unknown) => void;
+}) {
+  const { state, send } = useMachine(flow);
+
+  return (
+    <button
+      disabled={state.status !== "idle"}
+      onClick={() => void send({ type: "start" }).catch(onError)}
+    >
+      {state.status}
+    </button>
+  );
+}
+```
+
+The hook uses `useSyncExternalStore`. Rendering, resubscription and Strict Mode
+checks do not execute effects. The hook subscribes only: unmounting a subscriber
+**does not dispose a shared controller**. The owning application/route/session
+lifecycle must dispose it when its resource or identity scope ends. Create a fresh
+controller for the new scope; do not reuse one across tenants or users. Do not
+create a module-global controller for server requests. SSR needs equivalent
+request-local initial data on server and client for hydration. Do not send events
+from render or pure reducers. Strict Mode can replay caller-owned React Effects;
+an imperative call placed in such an Effect is still the caller's responsibility.
+
+See the fully typed [React purchase component](https://github.com/plutoframework/pluto-frontend/blob/main/examples/purchases/ApprovalButton.tsx)
+and the [flow/executor](https://github.com/plutoframework/pluto-frontend/blob/main/examples/purchases/approval.ts). These original examples
+are type-checked in CI and are independent of HeroUI/shadcn styling.
+
+## Backend authority
+
+A frontend interaction state such as `submitting` is distinct from the purchase's
+persisted business status. The backend verifies identity, RBAC, tenant scope,
+resource policy and state transitions on every write. Refresh authoritative query
+data after a mutation or uncertain failure. An aborted request can still commit
+on the server. UI request IDs correlate responses; they are not backend
+idempotency keys, authorization or an exactly-once guarantee. Preserve your
+feature mutation adapter's existing stable idempotency key for retries.
+
+## Develop
+
+Use Node 24.22.1:
+
+```sh
+npm ci
+npm run check
+npm run test:mutation
+npm pack
+```
+
+Tests cover transition rejection, duplicate actions, stale callbacks, reset,
+disposal, executor failures, React Strict Mode/SSR and 1,500 deterministic property
+runs over arbitrary event sequences. Mutation smoke is a bounded set of seeded
+mutations, not a comprehensive mutation engine. CI tests React 18.3.1 and 19.3.1.
+Releases publish through GitHub Actions using npm trusted publishing (OIDC);
+no npm credentials are stored in this repository or in GitHub Actions.
+
+## Publish a release
+
+The `publish.yml` workflow publishes stable `vMAJOR.MINOR.PATCH` tags using npm
+trusted publishing and provenance. It checks tag/version agreement and main-branch
+ancestry, runs tests and mutation checks, and verifies packed consumers before
+publishing. Prereleases are rejected. Manual dispatch accepts an existing tag for
+retrying a failed publish; npm never overwrites an already published version.
+
+After merging the intended changes into main:
+
+```sh
+npm version patch
+git push origin main --follow-tags
+```
+
+The one-time npm trusted publisher is scoped to:
+
+| Setting        | Value            |
+| -------------- | ---------------- |
+| Organization   | `plutoframework` |
+| Repository     | `pluto-frontend` |
+| Workflow       | `publish.yml`    |
+| Environment    | None             |
+| Allowed action | `npm publish`    |
+
+The workflow uses GitHub-hosted runners with `id-token: write`; npm exchanges the
+workflow identity for a short-lived publish credential. No `NPM_TOKEN` secret is
+needed. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+import type { Machine } from "../state/index.js";
+/** Subscribe only. The host owns the controller's reset/disposal lifecycle. */
+export declare function useMachine<State, Event>(machine: Machine<State, Event>): {
+    state: State;
+    send: (event: Event) => Promise<boolean>;
+};

package/dist/react/index.js

@@ -0,0 +1,7 @@
+"use client";
+import { useSyncExternalStore } from "react";
+/** Subscribe only. The host owns the controller's reset/disposal lifecycle. */
+export function useMachine(machine) {
+    const state = useSyncExternalStore(machine.subscribe, machine.getSnapshot, machine.getInitialSnapshot);
+    return { state, send: machine.send };
+}

package/dist/state/index.d.ts

@@ -0,0 +1,2 @@
+export { createMachine } from "./machine.js";
+export type { Decision, EffectContext, Machine, MachineOptions, Transition, } from "./types.js";

package/dist/state/index.js

@@ -0,0 +1 @@
+export { createMachine } from "./machine.js";

package/dist/state/machine.d.ts

@@ -0,0 +1,3 @@
+import type { Machine, MachineOptions } from "./types.js";
+/** One controller owns one interaction. Constructors perform no effects. */
+export declare function createMachine<State, Event, Effect = never>(options: MachineOptions<State, Event, Effect>): Machine<State, Event>;

package/dist/state/machine.js

@@ -0,0 +1,94 @@
+/** One controller owns one interaction. Constructors perform no effects. */
+export function createMachine(options) {
+    const { initial, transition, execute } = options;
+    let current = initial;
+    let epoch = 0;
+    let disposed = false;
+    let evaluating = false;
+    const listeners = new Set();
+    const executions = new Set();
+    function notify() {
+        for (const listener of [...listeners])
+            listener();
+    }
+    function cancel() {
+        // Fence callbacks BEFORE synchronous abort handlers can send events.
+        epoch++;
+        for (const controller of executions)
+            controller.abort();
+        executions.clear();
+    }
+    async function send(event) {
+        if (disposed)
+            return false;
+        if (evaluating)
+            throw new Error("Transitions must not send events");
+        const generation = epoch;
+        evaluating = true;
+        let decision;
+        try {
+            decision = transition(current, event);
+        }
+        finally {
+            evaluating = false;
+        }
+        if (!decision.accepted)
+            return false;
+        if (decision.effect !== undefined && !execute) {
+            throw new Error("An effect requires an executor");
+        }
+        const controller = new AbortController();
+        let active = true;
+        executions.add(controller);
+        current = decision.state;
+        try {
+            notify();
+            // Subscribers may reset/dispose the flow during notification.
+            if (generation !== epoch || disposed)
+                return true;
+            if (decision.effect !== undefined && execute) {
+                await execute(decision.effect, {
+                    signal: controller.signal,
+                    send: (next) => {
+                        if (!active || generation !== epoch || disposed) {
+                            return Promise.resolve(false);
+                        }
+                        return send(next);
+                    },
+                });
+            }
+            return true;
+        }
+        finally {
+            active = false;
+            executions.delete(controller);
+        }
+    }
+    return {
+        getSnapshot: () => current,
+        getInitialSnapshot: () => initial,
+        subscribe(listener) {
+            if (disposed)
+                return () => { };
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        send,
+        reset() {
+            if (disposed)
+                return;
+            cancel();
+            current = initial;
+            notify();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            cancel();
+            listeners.clear();
+        },
+    };
+}

package/dist/state/types.d.ts

@@ -0,0 +1,32 @@
+/** Domain facts belong in immutable state/events supplied by the host. */
+export type Decision<State, Effect = never> = {
+    readonly accepted: true;
+    readonly state: State;
+    readonly effect?: Effect;
+} | {
+    readonly accepted: false;
+    readonly state: State;
+};
+export type Transition<State, Event, Effect = never> = (current: State, event: Event) => Decision<State, Effect>;
+export interface EffectContext<Event> {
+    readonly signal: AbortSignal;
+    /** Scoped to this execution; returns false after reset/disposal/completion. */
+    readonly send: (event: Event) => Promise<boolean>;
+}
+export interface MachineOptions<State, Event, Effect = never> {
+    readonly initial: State;
+    readonly transition: Transition<State, Event, Effect>;
+    readonly execute?: (effect: Effect, context: EffectContext<Event>) => void | Promise<void>;
+}
+export interface Machine<State, Event> {
+    readonly getSnapshot: () => State;
+    /** Stable initial snapshot for SSR; host must hydrate equivalent initial data. */
+    readonly getInitialSnapshot: () => State;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Commits synchronously, resolves after its effect. Unexpected errors reject. */
+    readonly send: (event: Event) => Promise<boolean>;
+    /** Cancel outstanding executions, fence their callbacks, restore initial state. */
+    readonly reset: () => void;
+    /** Permanent teardown. Further events are rejected. */
+    readonly dispose: () => void;
+}

package/dist/state/types.js

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

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@plutoframework/frontend",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Explicit, typed frontend state transitions and React subscriptions for Pluto applications.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plutoframework/pluto-frontend.git"
+  },
+  "homepage": "https://github.com/plutoframework/pluto-frontend#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "fmt": "prettier --write .",
+    "check": "prettier --check . && tsc --noEmit && npm test && npm run build",
+    "test": "vitest run",
+    "test:mutation": "python3 scripts/mutation.py",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "5.0.5",
+    "fast-check": "4.10.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@testing-library/react": "16.3.3",
+    "jsdom": "30.1.3",
+    "prettier": "3.9.10"
+  }
+}