@pylonsync/functions 0.22.33 → 0.22.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Campbell Venture Studio, LLC
+
+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/dist/index.d.ts

@@ -19,7 +19,7 @@
  */
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
-export { workflow } from "./workflows";
+export { isWorkflowSignal, workflow } from "./workflows";
 export type { RawResponse, RawResponseInit } from "./response";
 export { agent, isAgentDefinition, validatorToJsonSchema, validatorSchemaToJsonSchema, } from "./agent";
 export type { AgentDefinition, AgentTool, AgentToolRun, AgentCallArgs, AgentResult, } from "./agent";

package/dist/workflows.d.ts

@@ -137,6 +137,17 @@ export declare function workflow<TInput = unknown>(name: string, fn: (wf: Workfl
 }): WorkflowDefinition<TInput>;
 /** Runtime shape check for a `workflows/` file's default export. */
 export declare function isWorkflowDefinition(v: unknown): v is WorkflowDefinition;
+/**
+ * Whether `err` is the engine pausing the workflow (a slice boundary or a
+ * wait), not a failure. A `try`/`catch` around steps in a workflow body must
+ * rethrow these untouched, or the workflow treats every pause as a crash:
+ *
+ *   catch (err) {
+ *     if (isWorkflowSignal(err)) throw err;
+ *     // real failure handling
+ *   }
+ */
+export declare function isWorkflowSignal(err: unknown): boolean;
 /**
  * Execute one slice of `def` for `request`, returning the engine verdict.
  * Never throws for handler errors — a step failure becomes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.22.33",
+  "version": "0.22.35",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -30,7 +30,8 @@
     "src",
     "dist",
     "assets",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "check": "tsc --noEmit",
@@ -45,7 +46,7 @@
     "functions",
     "database"
   ],
-  "license": "MIT OR Apache-2.0",
+  "license": "MIT",
   "dependencies": {
     "satori": "^0.26.0",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/index.ts

@@ -20,7 +20,7 @@
 
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
-export { workflow } from "./workflows";
+export { isWorkflowSignal, workflow } from "./workflows";
 export type { RawResponse, RawResponseInit } from "./response";
 export {
   agent,

package/src/ssr-client-bundler.test.ts

@@ -804,3 +804,14 @@ describe("nearestBoundaryComponent across route groups", () => {
     ).toBe("app/(marketing)/not-found");
   });
 });
+
+describe("client router popstate", () => {
+  test("a hash-only popstate does not re-render the route", () => {
+    // Clicking a same-page anchor fires popstate. Treating it as a navigation
+    // re-rendered the page and scrolled back to the top.
+    const src = fs.readFileSync(path.join(import.meta.dir, "ssr-client-bundler.ts"), "utf8");
+    const popstate = src.slice(src.indexOf('window.addEventListener("popstate"'));
+    expect(popstate).toContain("if (next === renderedPath) return;");
+    expect(src.match(/renderedPath = location\.pathname \+ location\.search;/g)?.length).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -830,6 +830,12 @@ function renderPendingPlaceholder(pathname, manifest, myEpoch) {
   return true;
 }
 
+// The path and query the page last rendered. A popstate that keeps them and
+// only changes the hash is a same-page jump (an anchor link, a back press
+// between anchors), not a navigation: re-rendering for it would reset the
+// scroll to the top.
+let renderedPath = "";
+
 async function navigate(href, opts) {
   const push = !opts || opts.push !== false;
   const url = new URL(href, location.href);
@@ -891,6 +897,7 @@ async function navigate(href, opts) {
           history.pushState({ component: matched.component }, "", target);
         }
         window.dispatchEvent(new Event("pylon:navigation"));
+        renderedPath = location.pathname + location.search;
         window.scrollTo(0, 0);
         didOptimistic = true;
       }
@@ -915,6 +922,7 @@ async function navigate(href, opts) {
       loadManifest().then((manifest) => {
         if (navState.settled || myEpoch !== navEpoch) return;
         if (renderPendingPlaceholder(url.pathname, manifest, myEpoch)) {
+          renderedPath = location.pathname + location.search;
           window.scrollTo(0, 0);
         }
       });
@@ -1013,6 +1021,7 @@ async function navigate(href, opts) {
     // re-read location after a Link click or a router.push(). popstate already
     // covers back/forward, but pushState/replaceState fire no event.
     window.dispatchEvent(new Event("pylon:navigation"));
+    renderedPath = location.pathname + location.search;
     // After a successful nav, scroll to top (Next.js default).
     window.scrollTo(0, 0);
   }
@@ -1042,8 +1051,11 @@ function installNavHandlers() {
     const seed = seeds ? seeds.get(link) : undefined;
     navigate(href, seed != null ? { seed } : undefined);
   });
+  renderedPath = location.pathname + location.search;
   window.addEventListener("popstate", () => {
-    navigate(location.pathname + location.search, { push: false });
+    const next = location.pathname + location.search;
+    if (next === renderedPath) return;
+    navigate(next, { push: false });
   });
   // Progressive-enhancement form submit (#276): intercept <form data-pylon-form>
   // so the page doesn't full-reload. fetch the same route.ts endpoint, follow

package/src/workflows.test.ts

@@ -15,6 +15,7 @@ import { describe, expect, test } from "bun:test";
 import {
   executeWorkflowSlice,
   isWorkflowDefinition,
+  isWorkflowSignal,
   workflow,
   type WorkflowRunRequest,
   type WorkflowStepResult,
@@ -264,3 +265,41 @@ describe("executeWorkflowSlice", () => {
     expect(res).toEqual({ action: "complete", output: { echoed: 42 } });
   });
 });
+
+describe("catching errors around steps", () => {
+  test("a pause is a workflow signal, not a failure, when the body catches it", async () => {
+    const failures: unknown[] = [];
+    const guarded = workflow("guarded", async (wf) => {
+      try {
+        await wf.step("one", () => 1);
+        await wf.step("two", () => 2);
+        return { ok: true };
+      } catch (err) {
+        if (isWorkflowSignal(err)) throw err;
+        failures.push(err);
+        throw err;
+      }
+    });
+    // Slice 0 runs step one and pauses at step two's boundary.
+    const res = await executeWorkflowSlice(guarded, req(0, []), ctx);
+    expect(res).toMatchObject({ action: "step_complete", step_name: "one" });
+    expect(failures).toEqual([]);
+  });
+
+  test("without the check, the body sees the pause as an error (the bug the helper prevents)", async () => {
+    const seen: string[] = [];
+    const careless = workflow("careless", async (wf) => {
+      try {
+        await wf.step("one", () => 1);
+        await wf.step("two", () => 2);
+      } catch (err) {
+        seen.push((err as Error).message);
+        throw err;
+      }
+    });
+    await executeWorkflowSlice(careless, req(0, []), ctx);
+    expect(seen).toEqual(["slice boundary"]);
+    expect(isWorkflowSignal(new Error("slice boundary"))).toBe(false);
+  });
+});
+

package/src/workflows.ts

@@ -178,6 +178,20 @@ class SliceBoundary extends Error {
   }
 }
 
+/**
+ * Whether `err` is the engine pausing the workflow (a slice boundary or a
+ * wait), not a failure. A `try`/`catch` around steps in a workflow body must
+ * rethrow these untouched, or the workflow treats every pause as a crash:
+ *
+ *   catch (err) {
+ *     if (isWorkflowSignal(err)) throw err;
+ *     // real failure handling
+ *   }
+ */
+export function isWorkflowSignal(err: unknown): boolean {
+  return err instanceof SliceBoundary || err instanceof WorkflowPaused;
+}
+
 /**
  * Execute one slice of `def` for `request`, returning the engine verdict.
  * Never throws for handler errors — a step failure becomes