@moku-labs/worker 0.1.4 → 0.2.1

package/README.md

@@ -33,7 +33,7 @@ export const app = createApp({
     server: {
       endpoints: [
         endpoint("/health").get(() => new Response("ok", { status: 200 })),
-        endpoint("/api/data/{lang?}").get(({ params }) =>
+        endpoint("/api/data/{lang:?}").get(({ params }) =>
           Response.json({ lang: params.lang ?? "en" })
         ),
         endpoint("/users/{userId}").get(

package/dist/config-Bj3GUJT_.d.cts

@@ -0,0 +1,63 @@
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/config.d.ts
+/** Per-request Cloudflare bindings object (env). Framework-level shared type. */
+type WorkerEnv = Record<string, unknown>;
+/** Global framework config — flat, with complete defaults. */
+type WorkerConfig = {
+  stage: "production" | "development" | "test";
+  name: string;
+  compatibilityDate: string;
+};
+/** Global framework events — declared once, visible to every plugin. */
+type WorkerEvents = {
+  "request:start": {
+    method: string;
+    path: string;
+    requestId: string;
+  };
+  "request:end": {
+    method: string;
+    path: string;
+    status: number;
+    ms: number;
+  };
+  "deploy:phase": {
+    phase: string;
+    detail?: string;
+  };
+  "deploy:complete": {
+    url: string;
+  };
+  "provision:resource": {
+    kind: "kv" | "r2" | "d1" | "queue" | "do";
+    name: string;
+  };
+};
+/**
+ * Worker-bound plugin context for Layer-3 consumer plugins. Aliases the core
+ * {@link PluginCtx} with the global {@link WorkerEvents} pre-merged into the event
+ * map, so a consumer plugin types its own `config`/`state`/`emit` by passing only
+ * its OWN event map — never hand-merging `WorkerEvents`, and never importing from
+ * `@moku-labs/core` (a Layer-1 boundary the spec validator flags for consumers).
+ *
+ * A plugin that resolves sibling plugins also needs a `require` field; intersect the
+ * public `Server.RequireFn` for it, exactly as this framework's own plugins do. When
+ * you need the unaliased shape (e.g. a different global event map), use the raw
+ * re-exported {@link PluginCtx} instead.
+ *
+ * @template Config - This plugin's own flat configuration object.
+ * @template State - This plugin's mutable state (use `Record<string, never>` when stateless).
+ * @template Events - This plugin's own event map, merged on top of {@link WorkerEvents}; defaults to none.
+ * @example
+ * ```typescript
+ * import type { Server, WorkerPluginCtx } from "@moku-labs/worker";
+ * type MyEvents = { "my:done": { id: string } };
+ * export type MyCtx = WorkerPluginCtx<MyConfig, Record<string, never>, MyEvents> & {
+ *   require: Server.RequireFn;
+ * };
+ * ```
+ */
+type WorkerPluginCtx<Config, State, Events extends Record<string, unknown> = Record<never, never>> = PluginCtx<Config, State, WorkerEvents & Events>;
+//#endregion
+export { WorkerPluginCtx as i, WorkerEnv as n, WorkerEvents as r, WorkerConfig as t };

package/dist/config-Bj3GUJT_.d.mts

@@ -0,0 +1,63 @@
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/config.d.ts
+/** Per-request Cloudflare bindings object (env). Framework-level shared type. */
+type WorkerEnv = Record<string, unknown>;
+/** Global framework config — flat, with complete defaults. */
+type WorkerConfig = {
+  stage: "production" | "development" | "test";
+  name: string;
+  compatibilityDate: string;
+};
+/** Global framework events — declared once, visible to every plugin. */
+type WorkerEvents = {
+  "request:start": {
+    method: string;
+    path: string;
+    requestId: string;
+  };
+  "request:end": {
+    method: string;
+    path: string;
+    status: number;
+    ms: number;
+  };
+  "deploy:phase": {
+    phase: string;
+    detail?: string;
+  };
+  "deploy:complete": {
+    url: string;
+  };
+  "provision:resource": {
+    kind: "kv" | "r2" | "d1" | "queue" | "do";
+    name: string;
+  };
+};
+/**
+ * Worker-bound plugin context for Layer-3 consumer plugins. Aliases the core
+ * {@link PluginCtx} with the global {@link WorkerEvents} pre-merged into the event
+ * map, so a consumer plugin types its own `config`/`state`/`emit` by passing only
+ * its OWN event map — never hand-merging `WorkerEvents`, and never importing from
+ * `@moku-labs/core` (a Layer-1 boundary the spec validator flags for consumers).
+ *
+ * A plugin that resolves sibling plugins also needs a `require` field; intersect the
+ * public `Server.RequireFn` for it, exactly as this framework's own plugins do. When
+ * you need the unaliased shape (e.g. a different global event map), use the raw
+ * re-exported {@link PluginCtx} instead.
+ *
+ * @template Config - This plugin's own flat configuration object.
+ * @template State - This plugin's mutable state (use `Record<string, never>` when stateless).
+ * @template Events - This plugin's own event map, merged on top of {@link WorkerEvents}; defaults to none.
+ * @example
+ * ```typescript
+ * import type { Server, WorkerPluginCtx } from "@moku-labs/worker";
+ * type MyEvents = { "my:done": { id: string } };
+ * export type MyCtx = WorkerPluginCtx<MyConfig, Record<string, never>, MyEvents> & {
+ *   require: Server.RequireFn;
+ * };
+ * ```
+ */
+type WorkerPluginCtx<Config, State, Events extends Record<string, unknown> = Record<never, never>> = PluginCtx<Config, State, WorkerEvents & Events>;
+//#endregion
+export { WorkerPluginCtx as i, WorkerEnv as n, WorkerEvents as r, WorkerConfig as t };

package/dist/index.cjs

@@ -121,17 +121,21 @@ const makeEndpoint = (path, method, handler) => ({
 	handler
 });
 /**
-* Build a typed `Endpoint`. `{name}` → required param; `{name?}` → optional param.
+* Build a typed `Endpoint`. `{name}` → required param (`string`); `{name:?}` →
+* optional param (`string | undefined`). The path template flows into each
+* handler's `ctx.params` ({@link PathParams}), so a required `{id}` is typed
+* `string` — no `?? ""` fallback needed.
 *
 * PURE factory (spec/03 §1): no ctx, no lifecycle, no side effects; safe to run
 * before `createApp`. Each verb method (`get`, `post`, …, `all`) returns the
 * truthful Endpoint value — `method: "ALL"` is never used as a `"get"` sentinel.
 *
-* @param path - Endpoint path, optionally with `{name}` / `{name?}` params.
+* @template Path - The path template literal, inferred from `path`.
+* @param path - Endpoint path, optionally with `{name}` / `{name:?}` params.
 * @returns A builder whose verb methods each return a typed `Endpoint`.
 * @example
 * ```typescript
-* endpoint("/api/data/{lang?}").get(({ params }) =>
+* endpoint("/api/data/{lang:?}").get(({ params }) =>
 *   Response.json({ lang: params.lang ?? "en" })
 * );
 * ```
@@ -232,27 +236,28 @@ const endpoint = (path) => ({
 const LITERAL_WEIGHT = 2;
 /** Specificity weight for a required param segment `{name}`. */
 const REQUIRED_PARAM_WEIGHT = 1;
-/** Specificity weight for an optional param segment `{name?}`. */
+/** Specificity weight for an optional param segment `{name:?}`. */
 const OPTIONAL_PARAM_WEIGHT = 0;
 /**
 * Parse one path segment string into a typed `PathSegment`.
 *
-* `{name}` → required param; `{name?}` → optional param; anything else → literal.
+* `{name}` → required param; `{name:?}` → optional param; anything else → literal.
+* The `:?` optional suffix matches the `@moku-labs/web` router pattern.
 *
 * @param raw - A single path segment token (no leading slash).
 * @returns The parsed `PathSegment`.
 * @example
 * ```typescript
-* parseSegment("{id}")  // → { value: "id", param: true, optional: false }
-* parseSegment("{id?}") // → { value: "id", param: true, optional: true }
-* parseSegment("api")   // → { value: "api", param: false, optional: false }
+* parseSegment("{id}")   // → { value: "id", param: true, optional: false }
+* parseSegment("{id:?}") // → { value: "id", param: true, optional: true }
+* parseSegment("api")    // → { value: "api", param: false, optional: false }
 * ```
 */
 const parseSegment = (raw) => {
 	if (raw.startsWith("{") && raw.endsWith("}")) {
 		const inner = raw.slice(1, -1);
-		if (inner.endsWith("?")) return {
-			value: inner.slice(0, -1),
+		if (inner.endsWith(":?")) return {
+			value: inner.slice(0, -2),
 			param: true,
 			optional: true
 		};
@@ -347,7 +352,7 @@ const tryMatchEndpoint = (compiled, method, tokens) => {
 * @example
 * ```typescript
 * const a = compileEndpoint(endpoint("/api/{id}").get(handler));   // specificity 3
-* const b = compileEndpoint(endpoint("/api/{id?}").get(handler));  // specificity 2
+* const b = compileEndpoint(endpoint("/api/{id:?}").get(handler));  // specificity 2
 * [b, a].sort(bySpecificityDesc); // → [a, b] — higher specificity first
 * ```
 */
@@ -390,10 +395,12 @@ const findBestMatch = (table, method, tokens) => {
 *
 * Called by `onInit` — the one-time per-isolate setup. Sorts `state.table` by
 * specificity (descending), validates that no endpoint path contains duplicate
-* `{param}` names, and sets `state.compiled = true` to guard re-entry.
+* `{param}` names or the retired `{name?}` optional syntax, and sets
+* `state.compiled = true` to guard re-entry.
 *
 * @param state - The mutable server state whose `table` should be compiled.
-* @throws {Error} With `[moku-worker]` prefix when a path has duplicate param names.
+* @throws {Error} With `[moku-worker]` prefix when a path has duplicate param
+*   names, or uses the old `{name?}` optional syntax (now `{name:?}`).
 * @example
 * ```typescript
 * // Called inside serverPlugin.onInit:
@@ -407,6 +414,10 @@ const compileServerState = (state) => {
 		const seen = /* @__PURE__ */ new Set();
 		for (const segment of compiled.segments) {
 			if (!segment.param) continue;
+			if (segment.value.endsWith("?")) {
+				const name = segment.value.slice(0, -1);
+				throw new Error(`[moku-worker] endpoint path "${compiled.endpoint.path}" uses the old optional-param syntax "{${segment.value}}".\n  Optional params now use the colon form (matching @moku-labs/web): write "{${name}:?}" instead of "{${name}?}".`);
+			}
 			if (seen.has(segment.value)) throw new Error(`[moku-worker] endpoint path "${compiled.endpoint.path}" has duplicate param "{${segment.value}}".\n  Each {param} name in a path must be unique.`);
 			seen.add(segment.value);
 		}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-AjH57AmD.cjs";
-import { PluginCtx, PluginInstance } from "@moku-labs/core";
+import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-Bj3GUJT_.cjs";
+import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 
 //#region \0rolldown/runtime.js
@@ -50,7 +50,7 @@ type BindingsApi = {
  * api-factory context. State slot is Record<string, never> — bindings holds NO
  * state (F4). Type-argument order is PluginCtx<Config, State, Events>.
  */
-type Context = PluginCtx<Config$4, Record<string, never>, WorkerEvents>;
+type Context = PluginCtx$1<Config$4, Record<string, never>, WorkerEvents>;
 //#endregion
 //#region src/plugins/bindings/index.d.ts
 /**
@@ -64,19 +64,19 @@ type Context = PluginCtx<Config$4, Record<string, never>, WorkerEvents>;
  */
 declare const bindingsPlugin: import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>;
 declare namespace types_d_exports$4 {
-  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
+  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathParams, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
 }
 /** HTTP method an endpoint matches; "ALL" matches any verb. */
 type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
-/** One parsed path segment: a literal, a required `{name}`, or an optional `{name?}`. */
+/** One parsed path segment: a literal, a required `{name}`, or an optional `{name:?}`. */
 type PathSegment = {
-  /** The literal text, or the param name when a param. */readonly value: string; /** Whether this segment is a `{name}` / `{name?}` parameter. */
-  readonly param: boolean; /** Whether the param is optional (`{name?}`). */
+  /** The literal text, or the param name when a param. */readonly value: string; /** Whether this segment is a `{name}` / `{name:?}` parameter. */
+  readonly param: boolean; /** Whether the param is optional (`{name:?}`). */
   readonly optional: boolean;
 };
 /** A declarative endpoint produced by the pure endpoint() builder. */
 type Endpoint = {
-  /** Endpoint path, optionally with `{name}` / `{name?}` params. */readonly path: string; /** HTTP method or "ALL". */
+  /** Endpoint path, optionally with `{name}` / `{name:?}` params. */readonly path: string; /** HTTP method or "ALL". */
   readonly method: Method; /** The handler invoked on a match. */
   readonly handler: EndpointHandler;
 };
@@ -125,14 +125,55 @@ type ApiOf<P> = P extends {
 } ? A : never;
 /** Cross-plugin reach used inside handlers: require(plugin) returns that plugin's API. Mirrors ctx.require. */
 type RequireFn = <P extends AnyPlugin>(plugin: P) => ApiOf<P>;
-/** A request handler: receives the per-request context, returns a Response. */
-type EndpointHandler = (ctx: RequestContext) => Response | Promise<Response>;
-/** Fresh per-request object threaded to each EndpointHandler. */
-type RequestContext = {
+/**
+ * Prettify an intersection into a single flat object type for readable hovers.
+ * Homomorphic mapped type — preserves each property's `?` optionality modifier.
+ */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Required param names in a path template, as a string union (`never` if none).
+ * Walks each `{...}` segment: collects a bare `{name}`, skips an optional `{name:?}`.
+ */
+type RequiredParamNames<Path extends string> = Path extends `${string}{${infer Rest}` ? Rest extends `${infer Body}}${infer Tail}` ? Body extends `${string}:?` ? RequiredParamNames<Tail> : Body | RequiredParamNames<Tail> : never : never;
+/**
+ * Optional param names in a path template with the `:?` suffix stripped, as a
+ * string union (`never` if none). Collects `{name:?}`, skips a bare `{name}`.
+ */
+type OptionalParamNames<Path extends string> = Path extends `${string}{${infer Rest}` ? Rest extends `${infer Body}}${infer Tail}` ? Body extends `${infer Name}:?` ? Name | OptionalParamNames<Tail> : OptionalParamNames<Tail> : never : never;
+/**
+ * Map a path template to its typed `params` object: a required `{name}` becomes
+ * `name: string`; an optional `{name:?}` becomes `name?: string`. A non-literal
+ * `string` path (e.g. one assembled at runtime) widens to the permissive
+ * `Record<string, string | undefined>`.
+ *
+ * @example
+ * ```typescript
+ * type P = PathParams<"/boards/{id}/data/{lang:?}">;
+ * // { id: string; lang?: string }
+ * ```
+ */
+type PathParams<Path extends string> = string extends Path ? Record<string, string | undefined> : Prettify<{ [K in RequiredParamNames<Path>]: string } & { [K in OptionalParamNames<Path>]?: string }>;
+/**
+ * A request handler: receives the per-request context, returns a Response.
+ *
+ * @template Params - Path-params shape, inferred by the `endpoint()` builder
+ *   from the path template ({@link PathParams}) — a required `{name}` is
+ *   `string`, an optional `{name:?}` is `string | undefined`. Defaults to the
+ *   permissive `Record<string, string | undefined>` for hand-written handler types.
+ */
+type EndpointHandler<Params = Record<string, string | undefined>> = (ctx: RequestContext<Params>) => Response | Promise<Response>;
+/**
+ * Fresh per-request object threaded to each EndpointHandler.
+ *
+ * @template Params - Path-params shape for `params`, inferred from the path
+ *   template by the `endpoint()` builder ({@link PathParams}). Defaults to the
+ *   permissive `Record<string, string | undefined>`.
+ */
+type RequestContext<Params = Record<string, string | undefined>> = {
   /** The incoming request. */readonly request: Request; /** Per-request Cloudflare bindings — threaded on the stack, NEVER stored in state. */
   readonly env: WorkerEnv; /** waitUntil / passThroughOnException. */
-  readonly exec: ExecutionContext; /** Path params extracted from the matched endpoint. */
-  readonly params: Record<string, string | undefined>; /** Parsed request URL. */
+  readonly exec: ExecutionContext; /** Path params extracted from the matched endpoint, typed from the path template. */
+  readonly params: Params; /** Parsed request URL. */
   readonly url: URL; /** Cross-plugin reach for handlers (e.g. require(bindingsPlugin)). */
   readonly require: RequireFn; /** Presence check for an optional plugin. */
   readonly has: (name: string) => boolean;
@@ -145,7 +186,7 @@ type ServerEvents = {
   };
 };
 /** Full server plugin context (own config + state + merged events + cross-plugin reach). */
-type ServerCtx = PluginCtx<ServerConfig, ServerState, WorkerEvents & ServerEvents> & {
+type ServerCtx = PluginCtx$1<ServerConfig, ServerState, WorkerEvents & ServerEvents> & {
   /** Cross-plugin require threaded into each RequestContext. */require: RequireFn; /** Presence check for an optional plugin. */
   has: (name: string) => boolean;
 };
@@ -175,12 +216,14 @@ type Api$3 = {
 /**
  * Fluent builder whose verb methods each return a typed `Endpoint`.
  *
+ * @template Path - The path template literal, used to infer each handler's
+ *   typed `ctx.params` ({@link PathParams}).
  * @example
  * ```typescript
- * const e = endpoint("/api/{id}").get(handler);
+ * const e = endpoint("/api/{id}").get(({ params }) => Response.json({ id: params.id }));
  * ```
  */
-type EndpointBuilder = {
+type EndpointBuilder<Path extends string> = {
   /**
    * Build a GET endpoint bound to this path.
    *
@@ -191,7 +234,7 @@ type EndpointBuilder = {
    * endpoint("/health").get(() => new Response("ok"));
    * ```
    */
-  get(handler: EndpointHandler): Endpoint;
+  get(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a POST endpoint bound to this path.
    *
@@ -202,7 +245,7 @@ type EndpointBuilder = {
    * endpoint("/users").post(({ request }) => Response.json({ created: true }, { status: 201 }));
    * ```
    */
-  post(handler: EndpointHandler): Endpoint;
+  post(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a PUT endpoint bound to this path.
    *
@@ -213,7 +256,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").put(({ params }) => Response.json({ updated: params.id }));
    * ```
    */
-  put(handler: EndpointHandler): Endpoint;
+  put(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a PATCH endpoint bound to this path.
    *
@@ -224,7 +267,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").patch(({ params }) => Response.json({ patched: params.id }));
    * ```
    */
-  patch(handler: EndpointHandler): Endpoint;
+  patch(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a DELETE endpoint bound to this path.
    *
@@ -235,7 +278,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").delete(() => new Response(null, { status: 204 }));
    * ```
    */
-  delete(handler: EndpointHandler): Endpoint;
+  delete(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a HEAD endpoint bound to this path.
    *
@@ -246,7 +289,7 @@ type EndpointBuilder = {
    * endpoint("/health").head(() => new Response(null, { status: 200 }));
    * ```
    */
-  head(handler: EndpointHandler): Endpoint;
+  head(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build an OPTIONS endpoint bound to this path.
    *
@@ -257,7 +300,7 @@ type EndpointBuilder = {
    * endpoint("/api").options(() => new Response(null, { headers: { Allow: "GET, POST" } }));
    * ```
    */
-  options(handler: EndpointHandler): Endpoint;
+  options(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build an ALL-method endpoint bound to this path (`method: "ALL"` — matches any verb).
    *
@@ -268,25 +311,29 @@ type EndpointBuilder = {
    * endpoint("0 * * * *").all(async () => new Response("cron done"));
    * ```
    */
-  all(handler: EndpointHandler): Endpoint;
+  all(handler: EndpointHandler<PathParams<Path>>): Endpoint;
 };
 /**
- * Build a typed `Endpoint`. `{name}` → required param; `{name?}` → optional param.
+ * Build a typed `Endpoint`. `{name}` → required param (`string`); `{name:?}` →
+ * optional param (`string | undefined`). The path template flows into each
+ * handler's `ctx.params` ({@link PathParams}), so a required `{id}` is typed
+ * `string` — no `?? ""` fallback needed.
  *
  * PURE factory (spec/03 §1): no ctx, no lifecycle, no side effects; safe to run
  * before `createApp`. Each verb method (`get`, `post`, …, `all`) returns the
  * truthful Endpoint value — `method: "ALL"` is never used as a `"get"` sentinel.
  *
- * @param path - Endpoint path, optionally with `{name}` / `{name?}` params.
+ * @template Path - The path template literal, inferred from `path`.
+ * @param path - Endpoint path, optionally with `{name}` / `{name:?}` params.
  * @returns A builder whose verb methods each return a typed `Endpoint`.
  * @example
  * ```typescript
- * endpoint("/api/data/{lang?}").get(({ params }) =>
+ * endpoint("/api/data/{lang:?}").get(({ params }) =>
  *   Response.json({ lang: params.lang ?? "en" })
  * );
  * ```
  */
-declare const endpoint: (path: string) => EndpointBuilder;
+declare const endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
 declare namespace types_d_exports$1 {
   export { Api$2 as Api, Config$3 as Config, D1Ctx, DeployManifest$2 as DeployManifest };
 }
@@ -370,7 +417,7 @@ type Api$2 = {
  * Internal context type — own config first, no state, no d1-local events.
  * Intersected with a narrow `require` typed to the one dependency d1 resolves.
  */
-type D1Ctx = PluginCtx<Config$3, Record<string, never>, WorkerEvents> & {
+type D1Ctx = PluginCtx$1<Config$3, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. d1 only ever resolves `bindingsPlugin`.
    *
@@ -446,7 +493,7 @@ type Api$1 = {
  * Internal context type — own config first, no state, no DO events.
  * Intersected with a narrow `require` typed to the one dependency durableObjects resolves.
  */
-type Ctx$1 = PluginCtx<Config$2, Record<string, never>, WorkerEvents> & {
+type Ctx$1 = PluginCtx$1<Config$2, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. durableObjects only ever resolves `bindingsPlugin`.
    *
@@ -685,7 +732,7 @@ type Api = {
  * (core's "advanced composition" note), typed to the one dependency queues resolves —
  * `require(bindingsPlugin)` → `BindingsApi`. Core does not export `RequireFunction`.
  */
-type Ctx = PluginCtx<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
+type Ctx = PluginCtx$1<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
   /**
    * Resolve a dependency plugin's api. queues only ever resolves `bindingsPlugin`.
    *
@@ -735,7 +782,7 @@ declare const serverPlugin: import("@moku-labs/core").PluginInstance<"server", S
     method: string;
   };
 }> & {
-  endpoint: (path: string) => EndpointBuilder;
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
 };
 //#endregion
 //#region src/plugins/storage/providers/types.d.ts
@@ -831,7 +878,7 @@ type StorageApi = {
  * resolves — mirrors the kv/api.ts pattern (PluginCtx has no `require` by
  * default; core does not export a generic RequireFunction).
  */
-type StorageCtx = PluginCtx<StorageConfig, Record<string, never>, WorkerEvents> & {
+type StorageCtx = PluginCtx$1<StorageConfig, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. storage only ever resolves bindingsPlugin.
    *
@@ -953,7 +1000,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
       method: string;
     };
   }> & {
-    endpoint: (path: string) => EndpointBuilder;
+    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
   }) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
     stage: "production" | "development" | "test";
   }, Record<string, never>, {
@@ -966,7 +1013,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
       method: string;
     };
   }> & {
-    endpoint: (path: string) => EndpointBuilder;
+    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
   }) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
     stage: "production" | "development" | "test";
   }, Record<string, never>, {
@@ -981,4 +1028,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     current: () => "production" | "development" | "test";
   }>]>>;
 //#endregion
-export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };
+export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type PluginCtx, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, type WorkerPluginCtx, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-AjH57AmD.mjs";
+import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-Bj3GUJT_.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
-import { PluginCtx, PluginInstance } from "@moku-labs/core";
+import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
 //#region \0rolldown/runtime.js
 declare namespace types_d_exports {
@@ -50,7 +50,7 @@ type BindingsApi = {
  * api-factory context. State slot is Record<string, never> — bindings holds NO
  * state (F4). Type-argument order is PluginCtx<Config, State, Events>.
  */
-type Context = PluginCtx<Config$4, Record<string, never>, WorkerEvents>;
+type Context = PluginCtx$1<Config$4, Record<string, never>, WorkerEvents>;
 //#endregion
 //#region src/plugins/bindings/index.d.ts
 /**
@@ -64,19 +64,19 @@ type Context = PluginCtx<Config$4, Record<string, never>, WorkerEvents>;
  */
 declare const bindingsPlugin: import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>;
 declare namespace types_d_exports$4 {
-  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
+  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathParams, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
 }
 /** HTTP method an endpoint matches; "ALL" matches any verb. */
 type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
-/** One parsed path segment: a literal, a required `{name}`, or an optional `{name?}`. */
+/** One parsed path segment: a literal, a required `{name}`, or an optional `{name:?}`. */
 type PathSegment = {
-  /** The literal text, or the param name when a param. */readonly value: string; /** Whether this segment is a `{name}` / `{name?}` parameter. */
-  readonly param: boolean; /** Whether the param is optional (`{name?}`). */
+  /** The literal text, or the param name when a param. */readonly value: string; /** Whether this segment is a `{name}` / `{name:?}` parameter. */
+  readonly param: boolean; /** Whether the param is optional (`{name:?}`). */
   readonly optional: boolean;
 };
 /** A declarative endpoint produced by the pure endpoint() builder. */
 type Endpoint = {
-  /** Endpoint path, optionally with `{name}` / `{name?}` params. */readonly path: string; /** HTTP method or "ALL". */
+  /** Endpoint path, optionally with `{name}` / `{name:?}` params. */readonly path: string; /** HTTP method or "ALL". */
   readonly method: Method; /** The handler invoked on a match. */
   readonly handler: EndpointHandler;
 };
@@ -125,14 +125,55 @@ type ApiOf<P> = P extends {
 } ? A : never;
 /** Cross-plugin reach used inside handlers: require(plugin) returns that plugin's API. Mirrors ctx.require. */
 type RequireFn = <P extends AnyPlugin>(plugin: P) => ApiOf<P>;
-/** A request handler: receives the per-request context, returns a Response. */
-type EndpointHandler = (ctx: RequestContext) => Response | Promise<Response>;
-/** Fresh per-request object threaded to each EndpointHandler. */
-type RequestContext = {
+/**
+ * Prettify an intersection into a single flat object type for readable hovers.
+ * Homomorphic mapped type — preserves each property's `?` optionality modifier.
+ */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Required param names in a path template, as a string union (`never` if none).
+ * Walks each `{...}` segment: collects a bare `{name}`, skips an optional `{name:?}`.
+ */
+type RequiredParamNames<Path extends string> = Path extends `${string}{${infer Rest}` ? Rest extends `${infer Body}}${infer Tail}` ? Body extends `${string}:?` ? RequiredParamNames<Tail> : Body | RequiredParamNames<Tail> : never : never;
+/**
+ * Optional param names in a path template with the `:?` suffix stripped, as a
+ * string union (`never` if none). Collects `{name:?}`, skips a bare `{name}`.
+ */
+type OptionalParamNames<Path extends string> = Path extends `${string}{${infer Rest}` ? Rest extends `${infer Body}}${infer Tail}` ? Body extends `${infer Name}:?` ? Name | OptionalParamNames<Tail> : OptionalParamNames<Tail> : never : never;
+/**
+ * Map a path template to its typed `params` object: a required `{name}` becomes
+ * `name: string`; an optional `{name:?}` becomes `name?: string`. A non-literal
+ * `string` path (e.g. one assembled at runtime) widens to the permissive
+ * `Record<string, string | undefined>`.
+ *
+ * @example
+ * ```typescript
+ * type P = PathParams<"/boards/{id}/data/{lang:?}">;
+ * // { id: string; lang?: string }
+ * ```
+ */
+type PathParams<Path extends string> = string extends Path ? Record<string, string | undefined> : Prettify<{ [K in RequiredParamNames<Path>]: string } & { [K in OptionalParamNames<Path>]?: string }>;
+/**
+ * A request handler: receives the per-request context, returns a Response.
+ *
+ * @template Params - Path-params shape, inferred by the `endpoint()` builder
+ *   from the path template ({@link PathParams}) — a required `{name}` is
+ *   `string`, an optional `{name:?}` is `string | undefined`. Defaults to the
+ *   permissive `Record<string, string | undefined>` for hand-written handler types.
+ */
+type EndpointHandler<Params = Record<string, string | undefined>> = (ctx: RequestContext<Params>) => Response | Promise<Response>;
+/**
+ * Fresh per-request object threaded to each EndpointHandler.
+ *
+ * @template Params - Path-params shape for `params`, inferred from the path
+ *   template by the `endpoint()` builder ({@link PathParams}). Defaults to the
+ *   permissive `Record<string, string | undefined>`.
+ */
+type RequestContext<Params = Record<string, string | undefined>> = {
   /** The incoming request. */readonly request: Request; /** Per-request Cloudflare bindings — threaded on the stack, NEVER stored in state. */
   readonly env: WorkerEnv; /** waitUntil / passThroughOnException. */
-  readonly exec: ExecutionContext; /** Path params extracted from the matched endpoint. */
-  readonly params: Record<string, string | undefined>; /** Parsed request URL. */
+  readonly exec: ExecutionContext; /** Path params extracted from the matched endpoint, typed from the path template. */
+  readonly params: Params; /** Parsed request URL. */
   readonly url: URL; /** Cross-plugin reach for handlers (e.g. require(bindingsPlugin)). */
   readonly require: RequireFn; /** Presence check for an optional plugin. */
   readonly has: (name: string) => boolean;
@@ -145,7 +186,7 @@ type ServerEvents = {
   };
 };
 /** Full server plugin context (own config + state + merged events + cross-plugin reach). */
-type ServerCtx = PluginCtx<ServerConfig, ServerState, WorkerEvents & ServerEvents> & {
+type ServerCtx = PluginCtx$1<ServerConfig, ServerState, WorkerEvents & ServerEvents> & {
   /** Cross-plugin require threaded into each RequestContext. */require: RequireFn; /** Presence check for an optional plugin. */
   has: (name: string) => boolean;
 };
@@ -175,12 +216,14 @@ type Api$3 = {
 /**
  * Fluent builder whose verb methods each return a typed `Endpoint`.
  *
+ * @template Path - The path template literal, used to infer each handler's
+ *   typed `ctx.params` ({@link PathParams}).
  * @example
  * ```typescript
- * const e = endpoint("/api/{id}").get(handler);
+ * const e = endpoint("/api/{id}").get(({ params }) => Response.json({ id: params.id }));
  * ```
  */
-type EndpointBuilder = {
+type EndpointBuilder<Path extends string> = {
   /**
    * Build a GET endpoint bound to this path.
    *
@@ -191,7 +234,7 @@ type EndpointBuilder = {
    * endpoint("/health").get(() => new Response("ok"));
    * ```
    */
-  get(handler: EndpointHandler): Endpoint;
+  get(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a POST endpoint bound to this path.
    *
@@ -202,7 +245,7 @@ type EndpointBuilder = {
    * endpoint("/users").post(({ request }) => Response.json({ created: true }, { status: 201 }));
    * ```
    */
-  post(handler: EndpointHandler): Endpoint;
+  post(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a PUT endpoint bound to this path.
    *
@@ -213,7 +256,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").put(({ params }) => Response.json({ updated: params.id }));
    * ```
    */
-  put(handler: EndpointHandler): Endpoint;
+  put(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a PATCH endpoint bound to this path.
    *
@@ -224,7 +267,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").patch(({ params }) => Response.json({ patched: params.id }));
    * ```
    */
-  patch(handler: EndpointHandler): Endpoint;
+  patch(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a DELETE endpoint bound to this path.
    *
@@ -235,7 +278,7 @@ type EndpointBuilder = {
    * endpoint("/users/{id}").delete(() => new Response(null, { status: 204 }));
    * ```
    */
-  delete(handler: EndpointHandler): Endpoint;
+  delete(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build a HEAD endpoint bound to this path.
    *
@@ -246,7 +289,7 @@ type EndpointBuilder = {
    * endpoint("/health").head(() => new Response(null, { status: 200 }));
    * ```
    */
-  head(handler: EndpointHandler): Endpoint;
+  head(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build an OPTIONS endpoint bound to this path.
    *
@@ -257,7 +300,7 @@ type EndpointBuilder = {
    * endpoint("/api").options(() => new Response(null, { headers: { Allow: "GET, POST" } }));
    * ```
    */
-  options(handler: EndpointHandler): Endpoint;
+  options(handler: EndpointHandler<PathParams<Path>>): Endpoint;
   /**
    * Build an ALL-method endpoint bound to this path (`method: "ALL"` — matches any verb).
    *
@@ -268,25 +311,29 @@ type EndpointBuilder = {
    * endpoint("0 * * * *").all(async () => new Response("cron done"));
    * ```
    */
-  all(handler: EndpointHandler): Endpoint;
+  all(handler: EndpointHandler<PathParams<Path>>): Endpoint;
 };
 /**
- * Build a typed `Endpoint`. `{name}` → required param; `{name?}` → optional param.
+ * Build a typed `Endpoint`. `{name}` → required param (`string`); `{name:?}` →
+ * optional param (`string | undefined`). The path template flows into each
+ * handler's `ctx.params` ({@link PathParams}), so a required `{id}` is typed
+ * `string` — no `?? ""` fallback needed.
  *
  * PURE factory (spec/03 §1): no ctx, no lifecycle, no side effects; safe to run
  * before `createApp`. Each verb method (`get`, `post`, …, `all`) returns the
  * truthful Endpoint value — `method: "ALL"` is never used as a `"get"` sentinel.
  *
- * @param path - Endpoint path, optionally with `{name}` / `{name?}` params.
+ * @template Path - The path template literal, inferred from `path`.
+ * @param path - Endpoint path, optionally with `{name}` / `{name:?}` params.
  * @returns A builder whose verb methods each return a typed `Endpoint`.
  * @example
  * ```typescript
- * endpoint("/api/data/{lang?}").get(({ params }) =>
+ * endpoint("/api/data/{lang:?}").get(({ params }) =>
  *   Response.json({ lang: params.lang ?? "en" })
  * );
  * ```
  */
-declare const endpoint: (path: string) => EndpointBuilder;
+declare const endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
 declare namespace types_d_exports$1 {
   export { Api$2 as Api, Config$3 as Config, D1Ctx, DeployManifest$2 as DeployManifest };
 }
@@ -370,7 +417,7 @@ type Api$2 = {
  * Internal context type — own config first, no state, no d1-local events.
  * Intersected with a narrow `require` typed to the one dependency d1 resolves.
  */
-type D1Ctx = PluginCtx<Config$3, Record<string, never>, WorkerEvents> & {
+type D1Ctx = PluginCtx$1<Config$3, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. d1 only ever resolves `bindingsPlugin`.
    *
@@ -446,7 +493,7 @@ type Api$1 = {
  * Internal context type — own config first, no state, no DO events.
  * Intersected with a narrow `require` typed to the one dependency durableObjects resolves.
  */
-type Ctx$1 = PluginCtx<Config$2, Record<string, never>, WorkerEvents> & {
+type Ctx$1 = PluginCtx$1<Config$2, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. durableObjects only ever resolves `bindingsPlugin`.
    *
@@ -685,7 +732,7 @@ type Api = {
  * (core's "advanced composition" note), typed to the one dependency queues resolves —
  * `require(bindingsPlugin)` → `BindingsApi`. Core does not export `RequireFunction`.
  */
-type Ctx = PluginCtx<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
+type Ctx = PluginCtx$1<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
   /**
    * Resolve a dependency plugin's api. queues only ever resolves `bindingsPlugin`.
    *
@@ -735,7 +782,7 @@ declare const serverPlugin: import("@moku-labs/core").PluginInstance<"server", S
     method: string;
   };
 }> & {
-  endpoint: (path: string) => EndpointBuilder;
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
 };
 //#endregion
 //#region src/plugins/storage/providers/types.d.ts
@@ -831,7 +878,7 @@ type StorageApi = {
  * resolves — mirrors the kv/api.ts pattern (PluginCtx has no `require` by
  * default; core does not export a generic RequireFunction).
  */
-type StorageCtx = PluginCtx<StorageConfig, Record<string, never>, WorkerEvents> & {
+type StorageCtx = PluginCtx$1<StorageConfig, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. storage only ever resolves bindingsPlugin.
    *
@@ -953,7 +1000,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
       method: string;
     };
   }> & {
-    endpoint: (path: string) => EndpointBuilder;
+    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
   }) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
     stage: "production" | "development" | "test";
   }, Record<string, never>, {
@@ -966,7 +1013,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
       method: string;
     };
   }> & {
-    endpoint: (path: string) => EndpointBuilder;
+    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
   }) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
     stage: "production" | "development" | "test";
   }, Record<string, never>, {
@@ -981,4 +1028,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     current: () => "production" | "development" | "test";
   }>]>>;
 //#endregion
-export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };
+export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type PluginCtx, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, type WorkerPluginCtx, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };

package/dist/index.mjs

@@ -120,17 +120,21 @@ const makeEndpoint = (path, method, handler) => ({
 	handler
 });
 /**
-* Build a typed `Endpoint`. `{name}` → required param; `{name?}` → optional param.
+* Build a typed `Endpoint`. `{name}` → required param (`string`); `{name:?}` →
+* optional param (`string | undefined`). The path template flows into each
+* handler's `ctx.params` ({@link PathParams}), so a required `{id}` is typed
+* `string` — no `?? ""` fallback needed.
 *
 * PURE factory (spec/03 §1): no ctx, no lifecycle, no side effects; safe to run
 * before `createApp`. Each verb method (`get`, `post`, …, `all`) returns the
 * truthful Endpoint value — `method: "ALL"` is never used as a `"get"` sentinel.
 *
-* @param path - Endpoint path, optionally with `{name}` / `{name?}` params.
+* @template Path - The path template literal, inferred from `path`.
+* @param path - Endpoint path, optionally with `{name}` / `{name:?}` params.
 * @returns A builder whose verb methods each return a typed `Endpoint`.
 * @example
 * ```typescript
-* endpoint("/api/data/{lang?}").get(({ params }) =>
+* endpoint("/api/data/{lang:?}").get(({ params }) =>
 *   Response.json({ lang: params.lang ?? "en" })
 * );
 * ```
@@ -231,27 +235,28 @@ const endpoint = (path) => ({
 const LITERAL_WEIGHT = 2;
 /** Specificity weight for a required param segment `{name}`. */
 const REQUIRED_PARAM_WEIGHT = 1;
-/** Specificity weight for an optional param segment `{name?}`. */
+/** Specificity weight for an optional param segment `{name:?}`. */
 const OPTIONAL_PARAM_WEIGHT = 0;
 /**
 * Parse one path segment string into a typed `PathSegment`.
 *
-* `{name}` → required param; `{name?}` → optional param; anything else → literal.
+* `{name}` → required param; `{name:?}` → optional param; anything else → literal.
+* The `:?` optional suffix matches the `@moku-labs/web` router pattern.
 *
 * @param raw - A single path segment token (no leading slash).
 * @returns The parsed `PathSegment`.
 * @example
 * ```typescript
-* parseSegment("{id}")  // → { value: "id", param: true, optional: false }
-* parseSegment("{id?}") // → { value: "id", param: true, optional: true }
-* parseSegment("api")   // → { value: "api", param: false, optional: false }
+* parseSegment("{id}")   // → { value: "id", param: true, optional: false }
+* parseSegment("{id:?}") // → { value: "id", param: true, optional: true }
+* parseSegment("api")    // → { value: "api", param: false, optional: false }
 * ```
 */
 const parseSegment = (raw) => {
 	if (raw.startsWith("{") && raw.endsWith("}")) {
 		const inner = raw.slice(1, -1);
-		if (inner.endsWith("?")) return {
-			value: inner.slice(0, -1),
+		if (inner.endsWith(":?")) return {
+			value: inner.slice(0, -2),
 			param: true,
 			optional: true
 		};
@@ -346,7 +351,7 @@ const tryMatchEndpoint = (compiled, method, tokens) => {
 * @example
 * ```typescript
 * const a = compileEndpoint(endpoint("/api/{id}").get(handler));   // specificity 3
-* const b = compileEndpoint(endpoint("/api/{id?}").get(handler));  // specificity 2
+* const b = compileEndpoint(endpoint("/api/{id:?}").get(handler));  // specificity 2
 * [b, a].sort(bySpecificityDesc); // → [a, b] — higher specificity first
 * ```
 */
@@ -389,10 +394,12 @@ const findBestMatch = (table, method, tokens) => {
 *
 * Called by `onInit` — the one-time per-isolate setup. Sorts `state.table` by
 * specificity (descending), validates that no endpoint path contains duplicate
-* `{param}` names, and sets `state.compiled = true` to guard re-entry.
+* `{param}` names or the retired `{name?}` optional syntax, and sets
+* `state.compiled = true` to guard re-entry.
 *
 * @param state - The mutable server state whose `table` should be compiled.
-* @throws {Error} With `[moku-worker]` prefix when a path has duplicate param names.
+* @throws {Error} With `[moku-worker]` prefix when a path has duplicate param
+*   names, or uses the old `{name?}` optional syntax (now `{name:?}`).
 * @example
 * ```typescript
 * // Called inside serverPlugin.onInit:
@@ -406,6 +413,10 @@ const compileServerState = (state) => {
 		const seen = /* @__PURE__ */ new Set();
 		for (const segment of compiled.segments) {
 			if (!segment.param) continue;
+			if (segment.value.endsWith("?")) {
+				const name = segment.value.slice(0, -1);
+				throw new Error(`[moku-worker] endpoint path "${compiled.endpoint.path}" uses the old optional-param syntax "{${segment.value}}".\n  Optional params now use the colon form (matching @moku-labs/web): write "{${name}:?}" instead of "{${name}?}".`);
+			}
 			if (seen.has(segment.value)) throw new Error(`[moku-worker] endpoint path "${compiled.endpoint.path}" has duplicate param "{${segment.value}}".\n  Each {param} name in a path must be unique.`);
 			seen.add(segment.value);
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/worker",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Cloudflare Worker framework for Moku — Durable Objects, Queues, R2, D1, and KV plugins that compose with Moku Web.",
   "repository": {
     "type": "git",

package/dist/config-AjH57AmD.d.cts

@@ -1,36 +0,0 @@
-//#region src/config.d.ts
-/** Per-request Cloudflare bindings object (env). Framework-level shared type. */
-type WorkerEnv = Record<string, unknown>;
-/** Global framework config — flat, with complete defaults. */
-type WorkerConfig = {
-  stage: "production" | "development" | "test";
-  name: string;
-  compatibilityDate: string;
-};
-/** Global framework events — declared once, visible to every plugin. */
-type WorkerEvents = {
-  "request:start": {
-    method: string;
-    path: string;
-    requestId: string;
-  };
-  "request:end": {
-    method: string;
-    path: string;
-    status: number;
-    ms: number;
-  };
-  "deploy:phase": {
-    phase: string;
-    detail?: string;
-  };
-  "deploy:complete": {
-    url: string;
-  };
-  "provision:resource": {
-    kind: "kv" | "r2" | "d1" | "queue" | "do";
-    name: string;
-  };
-};
-//#endregion
-export { WorkerEnv as n, WorkerEvents as r, WorkerConfig as t };

package/dist/config-AjH57AmD.d.mts

@@ -1,36 +0,0 @@
-//#region src/config.d.ts
-/** Per-request Cloudflare bindings object (env). Framework-level shared type. */
-type WorkerEnv = Record<string, unknown>;
-/** Global framework config — flat, with complete defaults. */
-type WorkerConfig = {
-  stage: "production" | "development" | "test";
-  name: string;
-  compatibilityDate: string;
-};
-/** Global framework events — declared once, visible to every plugin. */
-type WorkerEvents = {
-  "request:start": {
-    method: string;
-    path: string;
-    requestId: string;
-  };
-  "request:end": {
-    method: string;
-    path: string;
-    status: number;
-    ms: number;
-  };
-  "deploy:phase": {
-    phase: string;
-    detail?: string;
-  };
-  "deploy:complete": {
-    url: string;
-  };
-  "provision:resource": {
-    kind: "kv" | "r2" | "d1" | "queue" | "do";
-    name: string;
-  };
-};
-//#endregion
-export { WorkerEnv as n, WorkerEvents as r, WorkerConfig as t };