@acmekit/acmekit 2.13.88 → 2.13.90

package/dist/commands/plugin/develop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"develop.d.ts","sourceRoot":"","sources":["../../../src/commands/plugin/develop.ts"],"names":[],"mappings":"AAcA,wBAA8B,aAAa,CAAC,EAC1C,SAAS,GACV,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;CAClB,iBA0HA"}
+{"version":3,"file":"develop.d.ts","sourceRoot":"","sources":["../../../src/commands/plugin/develop.ts"],"names":[],"mappings":"AA+DA,wBAA8B,aAAa,CAAC,EAC1C,SAAS,GACV,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;CAClB,iBA8FA"}

package/dist/commands/plugin/develop.js

@@ -1,7 +1,19 @@
 "use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _DebouncedTask_instances, _DebouncedTask_timer, _DebouncedTask_running, _DebouncedTask_queued, _DebouncedTask_fn, _DebouncedTask_delay, _DebouncedTask_run;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = developPlugin;
 const build_tools_1 = require("@acmekit/framework/build-tools");
@@ -13,6 +25,53 @@ const ADMIN_REBUILD_DEBOUNCE_MS = 500;
 const ROUTE_TYPES_DEBOUNCE_MS = 300;
 const QUERY_TYPES_DEBOUNCE_MS = 300;
 const YALC_PUSH_DEBOUNCE_MS = 300;
+/**
+ * Debounces calls and serializes execution. If `schedule()` is called while
+ * the task is already running, a single follow-up execution is queued and
+ * runs after the current one completes — no concurrent executions.
+ */
+class DebouncedTask {
+    constructor(fn, delay) {
+        _DebouncedTask_instances.add(this);
+        _DebouncedTask_timer.set(this, null);
+        _DebouncedTask_running.set(this, false);
+        _DebouncedTask_queued.set(this, false);
+        _DebouncedTask_fn.set(this, void 0);
+        _DebouncedTask_delay.set(this, void 0);
+        __classPrivateFieldSet(this, _DebouncedTask_fn, fn, "f");
+        __classPrivateFieldSet(this, _DebouncedTask_delay, delay, "f");
+    }
+    schedule() {
+        if (__classPrivateFieldGet(this, _DebouncedTask_running, "f")) {
+            __classPrivateFieldSet(this, _DebouncedTask_queued, true, "f");
+            return;
+        }
+        if (__classPrivateFieldGet(this, _DebouncedTask_timer, "f"))
+            clearTimeout(__classPrivateFieldGet(this, _DebouncedTask_timer, "f"));
+        __classPrivateFieldSet(this, _DebouncedTask_timer, setTimeout(() => __classPrivateFieldGet(this, _DebouncedTask_instances, "m", _DebouncedTask_run).call(this), __classPrivateFieldGet(this, _DebouncedTask_delay, "f")), "f");
+    }
+    dispose() {
+        if (__classPrivateFieldGet(this, _DebouncedTask_timer, "f")) {
+            clearTimeout(__classPrivateFieldGet(this, _DebouncedTask_timer, "f"));
+            __classPrivateFieldSet(this, _DebouncedTask_timer, null, "f");
+        }
+        __classPrivateFieldSet(this, _DebouncedTask_queued, false, "f");
+    }
+}
+_DebouncedTask_timer = new WeakMap(), _DebouncedTask_running = new WeakMap(), _DebouncedTask_queued = new WeakMap(), _DebouncedTask_fn = new WeakMap(), _DebouncedTask_delay = new WeakMap(), _DebouncedTask_instances = new WeakSet(), _DebouncedTask_run = async function _DebouncedTask_run() {
+    __classPrivateFieldSet(this, _DebouncedTask_timer, null, "f");
+    __classPrivateFieldSet(this, _DebouncedTask_running, true, "f");
+    try {
+        await __classPrivateFieldGet(this, _DebouncedTask_fn, "f").call(this);
+    }
+    finally {
+        __classPrivateFieldSet(this, _DebouncedTask_running, false, "f");
+        if (__classPrivateFieldGet(this, _DebouncedTask_queued, "f")) {
+            __classPrivateFieldSet(this, _DebouncedTask_queued, false, "f");
+            this.schedule();
+        }
+    }
+};
 async function developPlugin({ directory, }) {
     const compiler = new build_tools_1.Compiler(directory, logger_1.logger);
     const parsedConfig = await compiler.loadTSConfigFile();
@@ -26,80 +85,49 @@ async function developPlugin({ directory, }) {
     if (!adminBuilt) {
         logger_1.logger.warn("[plugin:develop] Admin extensions build failed, continuing backend-only");
     }
-    // Debounced yalc push triggered after backend transpile or admin rebuild.
-    // Publishes to the store then pushes to all tracked installations.
-    let yalcPushTimeout = null;
-    const scheduleYalcPush = () => {
-        if (yalcPushTimeout)
-            clearTimeout(yalcPushTimeout);
-        yalcPushTimeout = setTimeout(async () => {
-            yalcPushTimeout = null;
-            try {
-                const synced = await (0, require_yalc_1.yalcPublishAndPush)(directory);
-                if (synced > 0) {
-                    logger_1.logger.info(`[plugin:develop] Synced to ${synced} app${synced > 1 ? "s" : ""}`);
-                }
+    const yalcPush = new DebouncedTask(async () => {
+        try {
+            const synced = await (0, require_yalc_1.yalcPublishAndPush)(directory);
+            if (synced > 0) {
+                logger_1.logger.info(`[plugin:develop] Synced to ${synced} app${synced > 1 ? "s" : ""}`);
             }
-            catch (err) {
-                logger_1.logger.warn(`[plugin:develop] Sync failed: ${err.message}`);
-            }
-        }, YALC_PUSH_DEBOUNCE_MS);
-    };
+        }
+        catch (err) {
+            logger_1.logger.warn(`[plugin:develop] Sync failed: ${err.message}`);
+        }
+    }, YALC_PUSH_DEBOUNCE_MS);
     // Sync to host apps immediately after the initial build so the
     // developer doesn't have to save a file to trigger the first push.
-    scheduleYalcPush();
-    // Debounced route-type regeneration triggered by API file changes
-    let routeTypesTimeout = null;
-    const scheduleRouteTypesRegen = () => {
-        if (routeTypesTimeout)
-            clearTimeout(routeTypesTimeout);
-        routeTypesTimeout = setTimeout(async () => {
-            routeTypesTimeout = null;
-            await compiler.generatePluginRouteTypes();
-            logger_1.logger.info("[plugin:develop] Route types updated");
-        }, ROUTE_TYPES_DEBOUNCE_MS);
-    };
-    // Debounced query-type regeneration triggered by module file changes
-    let queryTypesTimeout = null;
-    const scheduleQueryTypesRegen = () => {
-        if (queryTypesTimeout)
-            clearTimeout(queryTypesTimeout);
-        queryTypesTimeout = setTimeout(async () => {
-            queryTypesTimeout = null;
-            await compiler.generatePluginQueryTypes({ bustCache: true });
-            logger_1.logger.info("[plugin:develop] Query types updated");
-        }, QUERY_TYPES_DEBOUNCE_MS);
-    };
+    yalcPush.schedule();
+    const routeTypesRegen = new DebouncedTask(async () => {
+        await compiler.generatePluginRouteTypes();
+        logger_1.logger.info("[plugin:develop] Route types updated");
+    }, ROUTE_TYPES_DEBOUNCE_MS);
+    const queryTypesRegen = new DebouncedTask(async () => {
+        await compiler.generatePluginQueryTypes({ bustCache: true });
+        logger_1.logger.info("[plugin:develop] Query types updated");
+    }, QUERY_TYPES_DEBOUNCE_MS);
     // Watch for backend changes (transpiles src/ → .acmekit/server/src/)
     const transpiler = new build_tools_1.LocalPluginTranspiler({
         pluginRoot: directory,
         logger: logger_1.logger,
         onFileChange: (transpiledFilePath) => {
-            // Only regenerate when an API route file changed
             if (transpiledFilePath.includes(`${path_1.sep}api${path_1.sep}`)) {
-                scheduleRouteTypesRegen();
+                routeTypesRegen.schedule();
             }
-            // Regenerate query types when a module file changed
             if (transpiledFilePath.includes(`${path_1.sep}modules${path_1.sep}`)) {
-                scheduleQueryTypesRegen();
+                queryTypesRegen.schedule();
             }
-            scheduleYalcPush();
+            yalcPush.schedule();
         },
     });
     await transpiler.writeOptionsFile();
     await transpiler.watch();
     // Watch admin extensions for rebuild
-    let adminRebuildTimeout = null;
-    const scheduleAdminRebuild = () => {
-        if (adminRebuildTimeout) {
-            clearTimeout(adminRebuildTimeout);
-        }
-        adminRebuildTimeout = setTimeout(async () => {
-            adminRebuildTimeout = null;
-            await compiler.buildPluginAdminExtensions(bundler);
-            scheduleYalcPush();
-        }, ADMIN_REBUILD_DEBOUNCE_MS);
-    };
+    const adminRebuild = new DebouncedTask(async () => {
+        await compiler.buildPluginAdminExtensions(bundler);
+        yalcPush.schedule();
+    }, ADMIN_REBUILD_DEBOUNCE_MS);
     const adminWatcher = chokidar_1.default
         .watch("src/admin", {
         cwd: directory,
@@ -113,19 +141,15 @@ async function developPlugin({ directory, }) {
             "**/__admin-extensions__.js",
         ],
     })
-        .on("add", scheduleAdminRebuild)
-        .on("change", scheduleAdminRebuild)
-        .on("unlink", scheduleAdminRebuild);
+        .on("add", () => adminRebuild.schedule())
+        .on("change", () => adminRebuild.schedule())
+        .on("unlink", () => adminRebuild.schedule());
     // Graceful shutdown
     process.on("SIGINT", async () => {
-        if (yalcPushTimeout)
-            clearTimeout(yalcPushTimeout);
-        if (routeTypesTimeout)
-            clearTimeout(routeTypesTimeout);
-        if (queryTypesTimeout)
-            clearTimeout(queryTypesTimeout);
-        if (adminRebuildTimeout)
-            clearTimeout(adminRebuildTimeout);
+        yalcPush.dispose();
+        routeTypesRegen.dispose();
+        queryTypesRegen.dispose();
+        adminRebuild.dispose();
         await Promise.all([transpiler.close(), adminWatcher.close()]);
         process.exit(0);
     });

package/dist/commands/plugin/develop.js.map

@@ -1 +1 @@
-{"version":3,"file":"develop.js","sourceRoot":"","sources":["../../../src/commands/plugin/develop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"develop.js","sourceRoot":"","sources":["../../../src/commands/plugin/develop.ts"],"names":[],"mappings":"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"}

package/dist/templates/app/.claude/rules/admin-components.md

@@ -420,6 +420,8 @@ File: `src/admin/routes/custom/[id]/edit/page.tsx`
 
 **Critical structure**: Use `RouteDrawer.Form` wrapping `KeyboundForm` — this handles dirty form blocking on close and Cmd/Ctrl+Enter submit. The `KeyboundForm` wraps BOTH `RouteDrawer.Body` AND `RouteDrawer.Footer` so `type="submit"` works. Use `useRouteModal()` for `handleSuccess` to close the modal after success.
 
+**IMPORTANT**: `useRouteModal()` must be called in a **child component** rendered inside `<RouteDrawer>`, not in the same component that renders it. The `RouteModalProvider` context is created inside `RouteDrawer`, so calling the hook in the parent component crashes with "useRouteModal must be used within a RouteModalProvider".
+
 ```tsx
 import { Button, RouteDrawer, Form, Heading, Input, Textarea, toast, KeyboundForm, useRouteModal } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
@@ -434,39 +436,54 @@ const EditSchema = zod.object({
   description: zod.string().optional(),
 })
 
+// Page component — renders RouteDrawer, delegates form to child
 const EditPostPage = () => {
   const { id } = useParams()
-  const queryClient = useQueryClient()
-  const { handleSuccess } = useRouteModal()
 
   const { data, isLoading, isError, error } = useQuery({
     queryKey: ["posts", id],
     queryFn: () => sdk.admin.fetch("/posts/:id", { method: "GET", params: { id: id! } }),
   })
 
-  // Throw query errors to error boundary
   if (isError) {
     throw error
   }
 
+  return (
+    <RouteDrawer>
+      <RouteDrawer.Header>
+        <Heading>Edit Post</Heading>
+      </RouteDrawer.Header>
+      {!isLoading && data?.post && (
+        <EditPostForm post={data.post} />
+      )}
+    </RouteDrawer>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteDrawer)
+const EditPostForm = ({ post }: { post: { id: string; title: string; description?: string } }) => {
+  const queryClient = useQueryClient()
+  const { handleSuccess } = useRouteModal()
+
   const form = useForm<zod.infer<typeof EditSchema>>({
     defaultValues: {
-      title: data?.post?.title ?? "",
-      description: data?.post?.description ?? "",
+      title: post.title ?? "",
+      description: post.description ?? "",
     },
     resolver: zodResolver(EditSchema),
   })
 
   const { mutateAsync, isPending } = useMutation({
     mutationFn: (payload: zod.infer<typeof EditSchema>) =>
-      sdk.admin.fetch("/posts/:id", { method: "POST", params: { id: id! }, body: payload }),
+      sdk.admin.fetch("/posts/:id", { method: "POST", params: { id: post.id }, body: payload }),
   })
 
   const handleSubmit = form.handleSubmit(async (values) => {
     await mutateAsync(values, {
       onSuccess: () => {
         queryClient.invalidateQueries({ queryKey: ["posts"] })
-        queryClient.invalidateQueries({ queryKey: ["posts", id] })
+        queryClient.invalidateQueries({ queryKey: ["posts", post.id] })
         toast.success("Post updated")
         handleSuccess()
       },
@@ -475,57 +492,50 @@ const EditPostPage = () => {
   })
 
   return (
-    <RouteDrawer>
-      <RouteDrawer.Header>
-        <Heading>Edit Post</Heading>
-      </RouteDrawer.Header>
-      {!isLoading && data?.post && (
-        <RouteDrawer.Form form={form}>
-          <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col">
-            <RouteDrawer.Body>
-              <div className="flex flex-col gap-y-4">
-                <Form.Field
-                  control={form.control}
-                  name="title"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label>Title</Form.Label>
-                      <Form.Control>
-                        <Input autoComplete="off" {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-                <Form.Field
-                  control={form.control}
-                  name="description"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label optional>Description</Form.Label>
-                      <Form.Control>
-                        <Textarea {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-              </div>
-            </RouteDrawer.Body>
-            <RouteDrawer.Footer>
-              <div className="flex items-center justify-end gap-x-2">
-                <RouteDrawer.Close asChild>
-                  <Button size="small" variant="secondary">Cancel</Button>
-                </RouteDrawer.Close>
-                <Button size="small" type="submit" isLoading={isPending}>
-                  Save
-                </Button>
-              </div>
-            </RouteDrawer.Footer>
-          </KeyboundForm>
-        </RouteDrawer.Form>
-      )}
-    </RouteDrawer>
+    <RouteDrawer.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col">
+        <RouteDrawer.Body>
+          <div className="flex flex-col gap-y-4">
+            <Form.Field
+              control={form.control}
+              name="title"
+              render={({ field }) => (
+                <Form.Item>
+                  <Form.Label>Title</Form.Label>
+                  <Form.Control>
+                    <Input autoComplete="off" {...field} />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )}
+            />
+            <Form.Field
+              control={form.control}
+              name="description"
+              render={({ field }) => (
+                <Form.Item>
+                  <Form.Label optional>Description</Form.Label>
+                  <Form.Control>
+                    <Textarea {...field} />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )}
+            />
+          </div>
+        </RouteDrawer.Body>
+        <RouteDrawer.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteDrawer.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteDrawer.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Save
+            </Button>
+          </div>
+        </RouteDrawer.Footer>
+      </KeyboundForm>
+    </RouteDrawer.Form>
   )
 }
 
@@ -553,6 +563,8 @@ File: `src/admin/routes/custom/create/page.tsx`
 
 **Critical structure**: Use `RouteFocusModal.Form` wrapping `KeyboundForm` — this handles dirty form blocking on close and Cmd/Ctrl+Enter submit. The `KeyboundForm` wraps Header + Body + Footer. Use `useRouteModal()` for `handleSuccess` to close the modal after success.
 
+**IMPORTANT**: `useRouteModal()` must be called in a **child component** rendered inside `<RouteFocusModal>`, not in the same component that renders it. The `RouteModalProvider` context is created inside `RouteFocusModal`, so calling the hook in the parent component crashes with "useRouteModal must be used within a RouteModalProvider".
+
 ```tsx
 import { Button, RouteFocusModal, Form, Heading, Input, Text, Textarea, toast, KeyboundForm, useRouteModal } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
@@ -566,7 +578,17 @@ const CreateSchema = zod.object({
   description: zod.string().optional(),
 })
 
+// Page component — renders RouteFocusModal, delegates form to child
 const CreatePostPage = () => {
+  return (
+    <RouteFocusModal>
+      <CreatePostForm />
+    </RouteFocusModal>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteFocusModal)
+const CreatePostForm = () => {
   const queryClient = useQueryClient()
   const { handleSuccess } = useRouteModal()
 
@@ -592,61 +614,59 @@ const CreatePostPage = () => {
   })
 
   return (
-    <RouteFocusModal>
-      <RouteFocusModal.Form form={form}>
-        <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col overflow-hidden">
-          <RouteFocusModal.Header />
-          <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
-            <div className="flex w-full max-w-[720px] flex-col gap-y-8">
-              <div>
-                <Heading>Create Post</Heading>
-                <Text size="small" className="text-ui-fg-subtle">
-                  Add a new blog post.
-                </Text>
-              </div>
-              <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-                <Form.Field
-                  control={form.control}
-                  name="title"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label>Title</Form.Label>
-                      <Form.Control>
-                        <Input autoComplete="off" {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-                <Form.Field
-                  control={form.control}
-                  name="description"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label optional>Description</Form.Label>
-                      <Form.Control>
-                        <Textarea {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-              </div>
+    <RouteFocusModal.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col overflow-hidden">
+        <RouteFocusModal.Header />
+        <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
+          <div className="flex w-full max-w-[720px] flex-col gap-y-8">
+            <div>
+              <Heading>Create Post</Heading>
+              <Text size="small" className="text-ui-fg-subtle">
+                Add a new blog post.
+              </Text>
             </div>
-          </RouteFocusModal.Body>
-          <RouteFocusModal.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <RouteFocusModal.Close asChild>
-                <Button size="small" variant="secondary">Cancel</Button>
-              </RouteFocusModal.Close>
-              <Button size="small" type="submit" isLoading={isPending}>
-                Create
-              </Button>
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+              <Form.Field
+                control={form.control}
+                name="title"
+                render={({ field }) => (
+                  <Form.Item>
+                    <Form.Label>Title</Form.Label>
+                    <Form.Control>
+                      <Input autoComplete="off" {...field} />
+                    </Form.Control>
+                    <Form.ErrorMessage />
+                  </Form.Item>
+                )}
+              />
+              <Form.Field
+                control={form.control}
+                name="description"
+                render={({ field }) => (
+                  <Form.Item>
+                    <Form.Label optional>Description</Form.Label>
+                    <Form.Control>
+                      <Textarea {...field} />
+                    </Form.Control>
+                    <Form.ErrorMessage />
+                  </Form.Item>
+                )}
+              />
             </div>
-          </RouteFocusModal.Footer>
-        </KeyboundForm>
-      </RouteFocusModal.Form>
-    </RouteFocusModal>
+          </div>
+        </RouteFocusModal.Body>
+        <RouteFocusModal.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteFocusModal.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteFocusModal.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Create
+            </Button>
+          </div>
+        </RouteFocusModal.Footer>
+      </KeyboundForm>
+    </RouteFocusModal.Form>
   )
 }
 

package/dist/templates/app/.claude/rules/admin-data.md

@@ -313,6 +313,7 @@ const confirmed = await prompt({
 **Imports & dependencies:**
 - Importing `zod` from `"zod"` in admin code — use `import * as zod from "@acmekit/deps/zod"` to share the same zod instance as acmekit
 - Adding `react-hook-form` or `@hookform/resolvers` to `devDependencies` — they are provided by acmekit. In plugins: list them in `peerDependencies` (+ `devDependencies` mirror). In apps: they are available transitively, no extra dependency needed
+- Installing `@hookform/resolvers@5.x` — this version requires Zod v4 (`zod/v4/core`), but AcmeKit ships Zod v3. Causes `Could not resolve "zod/v4/core"` at build time. Never install your own version — use what AcmeKit provides
 
 **Form context:**
 - Using `Form.Field`, `Form.Label`, `SwitchBox`, or any `Form.*` sub-component without a form provider — they call `useFormContext()` and crash with "Cannot destructure property 'getFieldState' of 'useFormContext(...)' as it is null". `RouteDrawer.Form` / `RouteFocusModal.Form` provide this automatically; standalone pages must wrap with `<Form {...form}>` from `@acmekit/ui`
@@ -326,6 +327,7 @@ const confirmed = await prompt({
 - Using `onClick={handleSubmit}` on submit button — use `type="submit"` inside a `KeyboundForm` tag
 - Missing `className="flex flex-1 flex-col"` on the `KeyboundForm` tag (breaks layout)
 - Missing `overflow-hidden` on RouteFocusModal's `KeyboundForm` tag
+- Calling `useRouteModal()` in the same component that renders `RouteFocusModal`/`RouteDrawer` — the hook must be in a **child component** rendered inside the modal/drawer (the provider mounts inside it)
 - Using `navigate("..")` to close overlays instead of `handleSuccess()` from `useRouteModal()`
 - Putting footer buttons directly in Footer — wrap in `<div className="flex items-center justify-end gap-x-2">`
 - Using grid layout in Drawer forms — drawers are narrow, use single column `flex flex-col gap-y-4`