Release 1.15.0 — graduate all modules to Stable - #161

scripts/stability-matrix.mjs-3-13 (1)

3-13: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Stop maintaining a second canonical stability source.

This file now hard-codes the matrix and calls itself canonical, but STABILITY.md and the repo rules say the markdown record is the canonical stability source. That leaves two hand-edited authorities for the same release metadata, so the advertised “update STABILITY.md and run the check” workflow is no longer true. Please derive this module from STABILITY.md, or demote it to a generated mirror instead of another source of truth.

As per coding guidelines, STABILITY.md: “Maintain the canonical module stability record so the stable/beta/experimental status stays correct.”

Also applies to: 25-48

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/stability-matrix.mjs` around lines 3 - 13, The stability matrix is
currently being maintained as a second source of truth, which conflicts with the
canonical record in STABILITY.md. Update the module data in stability-matrix.mjs
so it is derived from or generated from STABILITY.md, or clearly demote this
file to a mirror used only for validation; keep
scripts/check-stability-matrix.mjs and the module history workflow aligned so
STABILITY.md remains the only hand-edited authority.

Source: Coding guidelines

src/plugin/define.ts-39-41 (1)

39-41: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Return the concrete plugin type from definePlugin().
BQueryPlugin<TOptions> collapses plugin-specific fields and narrow literals at the call site, so this helper no longer preserves the object shape it advertises. Use a generic like TPlugin extends BQueryPlugin<unknown> and return TPlugin instead.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/plugin/define.ts` around lines 39 - 41, `definePlugin()` is currently
returning the widened `BQueryPlugin<TOptions>` type, which loses plugin-specific
fields and literal precision at the call site. Update the `definePlugin` generic
so it accepts a concrete plugin type like `TPlugin extends
BQueryPlugin<unknown>` and returns `TPlugin` instead, while keeping the function
body as a simple identity return.

Source: Coding guidelines

src/server/session.ts-185-260 (1)

185-260: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Track nested session mutations before persisting.

The proxy only marks the session dirty for top-level assignment/deletion. Mutations like ctx.session.cart.items.push(item) update the in-memory object but never call markDirty(), so the change is skipped at finalize() and not written to the store.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/session.ts` around lines 185 - 260, The ServerSession proxy in
session.ts only marks dirty on top-level set/delete, so nested object/array
mutations can be missed before finalize(). Update the Proxy behavior around the
session object to detect or wrap nested mutations (for example in the get path
for data-backed values) so operations like ctx.session.cart.items.push(...)
trigger markDirty() and persist correctly. Use the existing session proxy,
markDirty(), and finalize() flow as the main touchpoints.

src/router/file-routes/data.ts-121-124 (1)

121-124: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Run loaders outside the reactive tracking frame.

run(route) starts synchronously inside effect(). If a loader reads signals before its first await, those signals can become dependencies and retrigger loading without navigation.

Proposed fix

   const dispose = effect(() => {
     const route = router.currentRoute.value;
-    void run(route);
+    queueMicrotask(() => {
+      void run(route);
+    });
   });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/router/file-routes/data.ts` around lines 121 - 124, The loader kickoff
inside the effect in the route watcher is running within the reactive tracking
frame, so any signals touched before the first await can become unintended
dependencies. Update the effect callback that reads router.currentRoute and
calls run(route) so the loader invocation happens outside tracking (for example
by deferring it or wrapping the call in a non-tracking boundary) while still
using the same route value. Keep the fix localized to the effect/run path in
data.ts so loaders are triggered only by navigation changes, not by reactive
reads inside loaders.

src/router/file-routes/routes.ts-80-132 (1)

80-132: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Reject duplicate file-route patterns.

routes/index.ts and routes/+page.ts both normalize to /; pathless groups can also collide. Returning both makes route resolution depend on manifest insertion order.

Proposed fix

   const entries: FileRoute[] = [];
+  const seenPatterns = new Map<string, string>();

   // Second pass: build a FileRoute per page.
   for (const [source, entry] of Object.entries(manifest)) {
     const parsed = parseFilePath(source, options);
     if (!parsed || parsed.kind !== 'page') continue;
+    const previousSource = seenPatterns.get(parsed.pattern);
+    if (previousSource) {
+      throw new Error(
+        `bQuery router: duplicate file route pattern "${parsed.pattern}" from "${previousSource}" and "${source}".`
+      );
+    }
+    seenPatterns.set(parsed.pattern, source);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/router/file-routes/routes.ts` around lines 80 - 132, The route builder in
routes.ts currently pushes every parsed page into entries without checking for
duplicate normalized patterns, so colliding files like routes/index.ts and
routes/+page.ts can both produce "/". Add a deduplication check in the second
pass around parseFilePath and entries.push, keyed by parsed.pattern, and reject
duplicates with a clear error instead of relying on manifest order. Use the
existing symbols parseFilePath, entries, and the page-building loop to locate
the change.

src/ssr/resumable-boundary.ts-304-327 (1)

304-327: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Deduplicate resumed handler bindings across nested boundaries.

wireBoundaryHandlers() scans every descendant for each boundary. If resumable boundaries are nested, a child handler can be wired once while scanning the parent and again while scanning the child, causing duplicate user actions.

Suggested fix

 const wireBoundaryHandlers = (
   scope: Element,
-  handlers: Record<string, ResumableHandler>
+  handlers: Record<string, ResumableHandler>,
+  wiredBindings: WeakMap<Element, Set<string>>
 ): number => {
@@
     const events = (el.getAttribute(RESUMABLE_EVENT_ATTR) ?? 'click')
       .split(/\s+/)
       .filter(Boolean);
     for (const event of events) {
+      const bindingKey = `${event}\u0000${handlerId}`;
+      let elementBindings = wiredBindings.get(el);
+      if (!elementBindings) {
+        elementBindings = new Set<string>();
+        wiredBindings.set(el, elementBindings);
+      }
+      if (elementBindings.has(bindingKey)) continue;
       el.addEventListener(event, fn as EventListener);
+      elementBindings.add(bindingKey);
       wired += 1;
     }
   }
@@
   const boundaryIds: string[] = [];
   const seededSignals: string[] = [];
+  const wiredBindings = new WeakMap<Element, Set<string>>();
   let wiredHandlers = 0;
@@
     if (root) {
       const scope = findBoundaryScope(root, boundary.id);
-      if (scope) wiredHandlers += wireBoundaryHandlers(scope, handlerRegistry);
+      if (scope) wiredHandlers += wireBoundaryHandlers(scope, handlerRegistry, wiredBindings);
     }

Also applies to: 404-407

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/ssr/resumable-boundary.ts` around lines 304 - 327, wireBoundaryHandlers()
is wiring the same resumable handler multiple times when nested boundaries are
scanned by both parent and child boundaries. Update the handler discovery in
wireBoundaryHandlers to skip elements that belong to a nested resumable boundary
so each handler is bound only once, and preserve the existing
RESUMABLE_HANDLER_ATTR/RESUMABLE_EVENT_ATTR behavior while preventing duplicate
addEventListener calls across nested scopes.

src/ssr/hydration.ts-133-188 (1)

133-188: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Guard hydration detection against evaluator failures.

hasResolvableRoot() only checks the leading identifier. Expressions like user.name when user is null can still throw and abort hydrate() before warn, repair, or error handling runs.

Suggested fix

+type EvaluationResult<T> = { ok: true; value: T } | { ok: false };
+
+const tryEvaluateExpression = <T>(
+  expression: string,
+  context: BindingContext
+): EvaluationResult<T> => {
+  try {
+    return { ok: true, value: evaluateExpression<T>(expression, context) };
+  } catch {
+    return { ok: false };
+  }
+};
+
   const textExpr = el.getAttribute(`${prefix}-text`);
   if (textExpr !== null && hasResolvableRoot(textExpr, context)) {
-    const clientValue = String(evaluateExpression<unknown>(textExpr, context) ?? '');
-    const domValue = el.textContent ?? '';
-    if (clientValue !== domValue) {
-      out.push({ element: el, kind: 'text', directive: `${prefix}-text`, domValue, clientValue });
+    const evaluated = tryEvaluateExpression<unknown>(textExpr, context);
+    if (evaluated.ok) {
+      const clientValue = String(evaluated.value ?? '');
+      const domValue = el.textContent ?? '';
+      if (clientValue !== domValue) {
+        out.push({ element: el, kind: 'text', directive: `${prefix}-text`, domValue, clientValue });
+      }
     }
   }

Apply the same wrapper to bq-show, bq-bind:*, and bq-model.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/ssr/hydration.ts` around lines 133 - 188, Guard hydration detection in
hydrate() against expression evaluator failures by wrapping the
evaluateExpression() calls used for bq-text, bq-show, bq-bind:*, and bq-model so
a bad nested access like user.name does not throw and abort the scan. Keep
hasResolvableRoot() as the precheck, but catch evaluator errors per directive,
skip reporting that candidate when evaluation fails, and continue collecting
mismatches so warn/repair/error handling still runs. Use the existing hydration
flow in src/ssr/hydration.ts and the directive-specific blocks around textExpr,
showExpr, attr.value, and modelExpr as the fix points.

src/concurrency/scheduling.ts-141-151 (1)

141-151: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Align deferred() timeout with the maximum-lag contract.

The cleanup cancels and reschedules the timeout on every source change, so continuous updates faster than timeout can keep the deferred signal stale indefinitely. That makes timeout a debounce delay, not the documented maximum lag. Either implement max-wait flushing of the latest value or rename/reword the option before this API is stabilized.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/concurrency/scheduling.ts` around lines 141 - 151, The `deferred()`
scheduling in `effect` currently behaves like a debounce because
`scheduleDeferred` is canceled and rescheduled on every source change, so
`mirror` may never update under constant churn. Update the logic around
`readDeferredSource`, `scheduleDeferred`, and the `mirror.value` assignment to
enforce a true maximum-lag contract by flushing the latest value after the
timeout even during continuous updates, or otherwise rename/reword
`options.timeout` to match the actual debounce behavior before stabilization.

src/concurrency/task.ts-125-139 (1)

125-139: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Thread options.runtime through the worker support checks in src/concurrency/task.ts and src/concurrency/rpc.ts. The module branch still falls back to plain typeof Worker, and the dynamic branch ignores the override entirely, so runtime: 'bun' | 'deno' | 'browser' | 'node' | 'unknown' cannot influence the guard and support can be reported incorrectly in tests and host-compat runtimes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/concurrency/task.ts` around lines 125 - 139, The worker support checks in
task/concurrency setup ignore the runtime override, so support detection can be
wrong for bun/deno/browser/node/unknown. Update the branching around
isWorkerModuleDescriptor in task.ts and the related guard logic in rpc.ts to
pass options.runtime through the support checks instead of relying only on
typeof Worker or the default environment. Use the existing symbols like
isConcurrencySupported, TaskWorkerUnsupportedError, createModuleWorkerInstance,
and createWorkerInstance to keep the runtime-specific path selection consistent.

src/concurrency/module-worker.ts-193-206 (1)

193-206: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Catch postMessage() serialization failures.

If a handler returns a non-cloneable result, scope.postMessage() throws from the success callback and no bq:error response is sent, leaving the main-thread call pending until timeout.

Proposed fix

-    void Promise.resolve()
-      .then(() => handler(message.payload as TInput))
-      .then(
-        (result) => {
-          scope.postMessage({ id: message.id, result, type: WORKER_RESULT_MESSAGE });
-        },
-        (error: unknown) => {
-          scope.postMessage({
-            error: serializeHostError(error),
-            id: message.id,
-            type: WORKER_ERROR_MESSAGE,
-          });
-        }
-      );
+    void (async () => {
+      try {
+        const result = await handler(message.payload as TInput);
+        scope.postMessage({ id: message.id, result, type: WORKER_RESULT_MESSAGE });
+      } catch (error) {
+        scope.postMessage({
+          error: serializeHostError(error),
+          id: message.id,
+          type: WORKER_ERROR_MESSAGE,
+        });
+      }
+    })();

Apply the same try/catch shape around the exposeRpc() handler result post.

Also applies to: 275-288

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/concurrency/module-worker.ts` around lines 193 - 206, The success path in
`module-worker.ts` is missing error handling around `scope.postMessage()` in the
`Promise.resolve().then(...).then(...)` flow, so non-cloneable handler results
can throw before a `WORKER_ERROR_MESSAGE` is sent. Wrap the `scope.postMessage({
id, result, type: WORKER_RESULT_MESSAGE })` call in the same `try/catch` shape
used elsewhere and, on failure, send a serialized error response with
`serializeHostError(error)` so the main thread doesn’t hang. Apply the same fix
to the matching `exposeRpc()` result posting path referenced by the other
affected block.

src/concurrency/module-worker.ts-43-58 (1)

43-58: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Separate task and RPC module descriptors.

defineWorker() and defineRpcWorker() currently produce identical branded descriptors, while createRpcWorker() treats any branded descriptor as RPC. Add an internal kind/separate brand and validate it in task/RPC factories so wrong descriptors fail fast instead of timing out. As per coding guidelines, src/**/*.ts: Do not weaken strict TypeScript type safety.

Also applies to: 74-99

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/concurrency/module-worker.ts` around lines 43 - 58, The branded
descriptor created by createModuleDescriptor is being reused for both task and
RPC workers, so defineWorker() and defineRpcWorker() can produce
indistinguishable objects. Add an internal kind field or separate brand in
createModuleDescriptor and the RPC descriptor creator, then make
createWorker/createRpcWorker validate that the descriptor kind matches the
factory before proceeding. Keep the TypeScript types strict by narrowing the
descriptor unions rather than weakening them, so invalid cross-use fails fast
instead of reaching createRpcWorker and timing out.

Source: Coding guidelines

src/i18n/extract/extract.ts-111-158 (1)

111-158: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Harden catalog reconstruction against prototype-polluting keys.

Both parseObjectLiteral() and unflatten() write source-derived path segments into plain {} objects. Keys like __proto__, constructor, or prototype can mutate the prototype chain and corrupt later merges/output.

Suggested fix

+const createCatalog = (): ExtractedCatalog => Object.create(null) as ExtractedCatalog;
+const isUnsafeKey = (key: string): boolean =>
+  key === '__proto__' || key === 'constructor' || key === 'prototype';
+
 const parseObjectLiteral = (
   src: string,
   start: number
 ): { value: ExtractedCatalog; end: number } => {
-  const obj: ExtractedCatalog = {};
+  const obj = createCatalog();
   let i = start + 1;
@@
     if (src[i] === '{') {
       const r = parseObjectLiteral(src, i);
-      obj[key] = r.value;
+      if (!isUnsafeKey(key)) obj[key] = r.value;
       i = r.end;
     } else if (src[i] === '"' || src[i] === "'" || src[i] === '`') {
       const r = readString(src, i);
-      obj[key] = r.value;
+      if (!isUnsafeKey(key)) obj[key] = r.value;
       i = r.end;
     } else {
       i = skipValue(src, i);
     }
@@
 export const unflatten = (messages: ExtractedMessage[]): ExtractedCatalog => {
-  const root: ExtractedCatalog = {};
+  const root = createCatalog();
   for (const { key, value } of [...messages].sort((a, b) => a.key.localeCompare(b.key))) {
     const parts = key.split('.');
     let node = root;
     for (let p = 0; p < parts.length - 1; p += 1) {
       const part = parts[p];
-      if (typeof node[part] !== 'object') node[part] = {};
+      if (isUnsafeKey(part)) throw new Error(`Unsafe catalog key: ${key}`);
+      if (typeof node[part] !== 'object') node[part] = createCatalog();
       node = node[part] as ExtractedCatalog;
     }
-    node[parts[parts.length - 1]] = value;
+    const leaf = parts[parts.length - 1];
+    if (isUnsafeKey(leaf)) throw new Error(`Unsafe catalog key: ${key}`);
+    node[leaf] = value;
   }
   return root;
 };

Also applies to: 173-185

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/i18n/extract/extract.ts` around lines 111 - 158, Harden the
catalog-building paths in parseObjectLiteral and unflatten so source-derived
keys cannot pollute object prototypes. Use a null-prototype container or
explicitly reject unsafe segments like __proto__, constructor, and prototype
before assigning into the plain object. Make the fix in the reconstruction logic
where obj is populated so both nested object parsing and flattened path
expansion are protected.

Source: Linters/SAST tools

src/i18n/extract/cli.ts-111-118 (1)

111-118: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Do not treat every catalog read/parse failure as “missing file.”

If options.out already exists but contains malformed JSON or is unreadable, readJsonCatalog() returns {} and extractFiles() then overwrites that file with a fresh catalog. That silently destroys existing translations instead of surfacing the real error.

Suggested fix

 const readJsonCatalog = async (file: string): Promise<ExtractedCatalog> => {
   const { readFile } = await import('node:fs/promises');
   try {
     const text = await readFile(file, 'utf8');
     return JSON.parse(text) as ExtractedCatalog;
-  } catch {
-    return {};
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
   }
 };

Also applies to: 156-159

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/i18n/extract/cli.ts` around lines 111 - 118, The readJsonCatalog helper
currently swallows every read/parse error and returns an empty catalog, which
makes extractFiles overwrite an existing out file even when it is malformed or
unreadable. Update readJsonCatalog to distinguish a missing file from other
failures: keep returning an empty object only for the “file not found” case, and
rethrow or surface JSON parse/read errors so extractFiles does not replace
existing translations with a fresh catalog. Use the readJsonCatalog and
extractFiles flow to locate the fix.

src/i18n/extract/extract.ts-173-183 (1)

173-183: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Reject parent/child key collisions instead of silently dropping one translation.

unflatten() overwrites data when both a and a.b are present: the later nested write coerces a from a string into an object and loses the original value. Since the extractor accepts arbitrary dot-delimited keys, this can silently discard messages during merge/write.

Suggested fix

   for (const { key, value } of [...messages].sort((a, b) => a.key.localeCompare(b.key))) {
     const parts = key.split('.');
     let node = root;
     for (let p = 0; p < parts.length - 1; p += 1) {
       const part = parts[p];
-      if (typeof node[part] !== 'object') node[part] = createCatalog();
-      node = node[part] as ExtractedCatalog;
+      const existing = node[part];
+      if (typeof existing === 'string') {
+        throw new Error(`Catalog key collision: "${parts.slice(0, p + 1).join('.')}" conflicts with "${key}"`);
+      }
+      if (existing === undefined) node[part] = createCatalog();
+      node = node[part] as ExtractedCatalog;
     }
-    node[parts[parts.length - 1]] = value;
+    const leaf = parts[parts.length - 1];
+    if (typeof node[leaf] === 'object') {
+      throw new Error(`Catalog key collision: "${key}" conflicts with nested keys`);
+    }
+    node[leaf] = value;
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/i18n/extract/extract.ts` around lines 173 - 183, unflatten currently
allows parent/child key collisions, so a key like a can be overwritten when a.b
is processed and one translation is lost. Update unflatten in extract.ts to
detect conflicts while walking parts, especially in the loop that builds node
from ExtractedMessage.key, and reject any case where an intermediate segment
already holds a non-object value or the final key already exists as an
object/value conflict. Surface this as an explicit error instead of coercing
node[part] into {} so the caller can handle the invalid catalog shape.

src/forms/types.ts-303-313 (1)

303-313: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

The documented getKey guarantee is broader than the current implementation.

This says keyed arrays enforce the contract on every structural mutation, but createFieldArray.move() still just reorders items without re-running assertStableKeys(). A getKey(value, index) can be valid on insert/add and become invalid after a reorder, so either validate on move as well or narrow the public contract here.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/forms/types.ts` around lines 303 - 313, The documented getKey contract in
FormFieldArray is broader than what move currently enforces, since
createFieldArray.move() only reorders items and does not re-run
assertStableKeys(). Update the move path to validate keys after reordering
(using assertStableKeys and the existing getKey contract) so invalid or
duplicate keys are caught on every structural mutation, or else narrow the
getKey documentation/comments in src/forms/types.ts to match the actual
behavior.

src/forms/action.ts-201-223 (1)

201-223: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

pending flips false too early when submits overlap.

Each submit() call sets the shared boolean back to false in finally, so the first completion clears pending even if a later submit is still in flight. Track an in-flight count/token and derive pending from that, otherwise useFormStatus() misreports active work.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/forms/action.ts` around lines 201 - 223, The shared pending state in
submit() is being cleared by whichever request finishes first, so overlapping
submissions can incorrectly report no active work. Update the useFormAction flow
around submit(), pending, and submitCount to track in-flight submits with a
count or token instead of a single boolean, and only set pending false when the
last active submit completes. Keep the existing optimistic overlay cleanup and
onSuccess/onError handling inside submit() unchanged aside from tying pending to
the active submit tracking.

src/forms/action.ts-142-148 (1)

142-148: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Preserve the clicked submitter in enhanced submits.

new FormData(form) omits the clicked submit button, so enhanced submits lose button name/value data and can diverge from native behavior when a form has multiple submit actions. Capture the SubmitEvent.submitter and build the payload from that submit context instead of the bare form.

Also applies to: 253-258

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/forms/action.ts` around lines 142 - 148, The enhanced form payload
builder in buildFormData currently uses only the form element, so the clicked
submit button’s name/value is lost and behavior can diverge from native submits.
Update the submit handling path to capture SubmitEvent.submitter and pass that
submit context into buildFormData (and any other enhanced submit helpers that
construct FormData) so the final payload preserves the clicked button data.

src/forms/action.ts-175-191 (1)

175-191: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Don't send FormData in the enhanced GET path.

formAction({ method: 'GET' }) still calls fetch() with body: formData. That breaks the enhanced flow, because GET submissions need to be encoded into the query string and sent without a body. Right now the native fallback and JS-enhanced behavior diverge for the same API surface.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/forms/action.ts` around lines 175 - 191, The enhanced GET path in
runTarget is still sending formData as a request body, which must be removed to
match native GET behavior. Update formAction’s runTarget logic to branch on the
normalized method before calling fetchImpl: for GET, serialize the FormData into
the target URL query string and call fetch without a body; for non-GET, keep the
existing body submission. Use the existing method, target, and runTarget symbols
to locate and adjust the request construction.

src/view/directives/show.ts-54-62 (1)

54-62: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Stop async hide commits after cleanup.

Like bq-if, a pending leave transition can still commit display: none after the directive cleanup runs. Wrap the cleanup to invalidate the token and cancel active animations.

🐛 Proposed fix

-    cleanups.push(cleanup);
+    cleanups.push(() => {
+      token++;
+      cancelTransitions(el);
+      cleanup();
+    });

Also applies to: 69-69

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/directives/show.ts` around lines 54 - 62, The pending leave
transition in show.ts can still commit a hide after directive cleanup, so update
the cleanup path to invalidate the current transition token and cancel any
active animations. Use the existing token check around runTransition,
cancelTransitions, and the show directive’s cleanup registration so that cleanup
prevents the then() callback from setting htmlEl.style.display = 'none' once the
directive has been torn down.

src/view/process.ts-15-15 (1)

15-15: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Don’t globally shadow custom directive names.

This guard runs before plugin custom-directive lookup, so a previously valid custom directive like bq-transition or bq-in is now silently ignored even when no bq-if/bq-show/bq-for owns it. Only skip companion attributes when an owning directive is present.

🐛 Proposed fix

-const PASSIVE_DIRECTIVES = new Set<string>(['key', ...TRANSITION_ATTRS]);
+const TRANSITION_DIRECTIVES = new Set<string>(TRANSITION_ATTRS);

-    // Skip companion attributes (bq-key, bq-transition, bq-in, bq-out, …) that
-    // are read by their owning directive rather than processed here.
-    if (PASSIVE_DIRECTIVES.has(directive)) continue;
+    const hasStructuralTransitionOwner =
+      TRANSITION_DIRECTIVES.has(directive) &&
+      (el.hasAttribute(`${prefix}-if`) ||
+        el.hasAttribute(`${prefix}-show`) ||
+        el.hasAttribute(`${prefix}-for`));
+    const hasForKeyOwner = directive === 'key' && el.hasAttribute(`${prefix}-for`);
+
+    // Skip companion attributes only when their owning directive will consume them.
+    if (hasStructuralTransitionOwner || hasForKeyOwner) continue;

Also applies to: 72-74

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/process.ts` at line 15, The PASSIVE_DIRECTIVES guard in process.ts
is too broad and can shadow valid custom directives before the custom-directive
lookup runs. Update the logic around PASSIVE_DIRECTIVES and the directive
handling in the process flow so companion attributes like bq-transition or bq-in
are skipped only when an owning directive such as bq-if, bq-show, or bq-for is
actually present. Make sure the affected directive-processing path preserves
custom directives otherwise, using the relevant checks in the process function
and any related companion-attribute filtering.

src/view/directives/if.ts-57-63 (1)

57-63: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Cancel pending transitions during directive cleanup.

A pending leave transition can still run its .then(...) after View.destroy() because cleanup only stops the effect. Invalidate the token and cancel animations in the registered cleanup.

🐛 Proposed fix

-    cleanups.push(cleanup);
+    cleanups.push(() => {
+      token++;
+      cancelTransitions(el);
+      cleanup();
+    });

Also applies to: 74-74

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/directives/if.ts` around lines 57 - 63, The pending leave transition
in the if directive can still complete after cleanup because the registered
effect teardown only stops reactivity. Update the cleanup path around
runTransition, myToken/token, and cancelTransitions so that directive
destruction invalidates the current token and explicitly cancels any in-flight
animations before the promise callback can call replaceWith or change
isInserted. Make sure the cleanup used by the if directive covers both the leave
transition and any related enter/leave state so View.destroy cannot leave a
stale .then(...) running.

src/view/directives/transitions.ts-197-201 (1)

197-201: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Catch animate() setup errors and fall back to the no-transition path. Element.animate() throws synchronously for invalid easing/timing values, so runTransition() can reject before any finish handler is wired. The bq-if/bq-show leave paths only use .then(...), so the element can stay mounted or visible instead of taking the synchronous commit path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/directives/transitions.ts` around lines 197 - 201, `runTransition()`
is calling `animatable.animate()` in a way that can throw before the transition
promise is created, which leaves the `bq-if`/`bq-show` leave flow without a
fallback. Update the `animate()` setup in `transitions.ts` to catch synchronous
setup errors around the `animate()` call and treat them as a no-transition case,
so the existing commit path is taken when timing/easing values are invalid. Use
the `runTransition` and `animatable.animate` logic as the anchor points for the
fix.

src/view/compiler/expression.ts-24-30 (1)

24-30: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Preserve runtime global fallback for non-whitelisted identifiers.

The runtime evaluator falls through to ambient scope for any name missing from ctx, but the compiled path only preserves that behavior for names hard-coded in DEFAULT_GLOBALS. Expressions like URL.createObjectURL(file) currently compile to __bq_ctx.URL.createObjectURL(__bq_ctx.file), which changes behavior instead of matching runtime semantics. Emit a fallback lookup such as ("URL" in ctx ? ctx.URL : URL) for unknown names, or bail out unless the identifier is known to come from the binding context.

Possible fix

-      out += `${param}.${name}`;
+      out += `(${JSON.stringify(name)} in ${param} ? ${param}.${name} : ${name})`;

Also applies to: 245-275

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/compiler/expression.ts` around lines 24 - 30, The compiled
expression path in expression.ts is incorrectly limiting global fallback to only
DEFAULT_GLOBALS, so unknown identifiers no longer match the runtime with(ctx)
behavior. Update the identifier compilation logic used by the expression
compiler to emit a context-or-global fallback for any name not known to be a
binding-context value, or explicitly reject/bail out when the symbol cannot be
proven local. Make sure the fix is applied in the identifier handling around
DEFAULT_GLOBALS and the expression compilation flow that produces references
like __bq_ctx.<name>, so cases such as URL.createObjectURL(file) continue to
resolve against ambient globals when ctx does not provide the name.

src/view/compiler/cli.ts-61-66 (1)

61-66: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

--out-dir can overwrite outputs from different source folders.

When outDir is set, every file is written to ${outDir}/${basename}${suffix}${ext}. Compiling pages/home/index.html and emails/home/index.html will silently target the same output path and drop one result. Preserve the relative input path under outDir, or detect collisions and fail fast.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/compiler/cli.ts` around lines 61 - 66, The output path logic in
cli.ts currently uses only path.basename in the write step, so different source
folders can collide when --out-dir is set. Update the compile flow around the
output construction and writeFile call to preserve each input file’s relative
path under options.outDir (or, if that’s not desired, detect duplicate targets
and throw before writing). Use the existing input, base, dir, suffix, and ext
handling in the cli compiler path to locate the fix.

src/view/compiler/expression.ts-143-152 (1)

143-152: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Don't mark syntactically invalid rewrites as compiled.

rewrite() tokenizes conservatively, but it never proves that the final body is still valid JavaScript. Inputs like count + or items] can return { ok: true } and then generate an invalid module, turning one bad directive into an import-time failure instead of a normal runtime fallback. Add a final syntax/balance validation step before returning ok: true, and convert failures to ok: false.

Also applies to: 217-223, 336-338

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/compiler/expression.ts` around lines 143 - 152, The rewrite() flow
is currently returning ok: true even when the rewritten expression is still
syntactically invalid, which can produce an invalid module; add a final
syntax/balance validation step before the success return and downgrade any
invalid result to ok: false. Use the existing rewrite() path in expression.ts,
including the string/token handling and any final assembly logic, to verify
parentheses/brackets/quotes and overall JavaScript validity before marking the
body as compiled.

src/view/compiler/cli.ts-95-112 (1)

95-112: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Don't consume the next flag as an option value.

Each option blindly uses argv[++i]. If the user forgets a value, the parser will happily treat the next flag as data (--prefix --out-dir sets prefix="--out-dir"), which produces confusing behavior instead of the documented usage error. Validate that a non-flag value exists before assigning each option.

Possible fix

+  const takeValue = (flag: string): string | null => {
+    const value = argv[i + 1];
+    if (!value || value.startsWith('-')) {
+      io.error(`Missing value for ${flag}`);
+      return null;
+    }
+    i++;
+    return value;
+  };
+
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     switch (arg) {
-      case '--prefix':
-        options.prefix = argv[++i];
+      case '--prefix': {
+        const value = takeValue('--prefix');
+        if (value === null) return 1;
+        options.prefix = value;
         break;
-      case '--out-dir':
-        options.outDir = argv[++i];
+      }
+      case '--out-dir': {
+        const value = takeValue('--out-dir');
+        if (value === null) return 1;
+        options.outDir = value;
         break;
+      }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/view/compiler/cli.ts` around lines 95 - 112, The CLI parser in the argv
loop is consuming the next token with argv[++i] for option values, which can
incorrectly treat another flag as data when a value is missing. Update the
parsing logic in cli.ts around the switch handling for --prefix, --out-dir,
--suffix, --ext, and --import to first verify that argv[i + 1] exists and is not
a flag before assigning it to options. If the next token is missing or starts
with --, fail with the same usage/error path used by the parser instead of
advancing i.

extension/panel.js-68-70 (1)

68-70: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not render inspected-page data through innerHTML.

fmt(item) and e.label come from the inspected page and are injected straight into the extension DOM. In the panel this crosses a privilege boundary and lets page-controlled markup rewrite or spoof the extension UI. Build these rows with textContent/DOM nodes (or sanitize first) instead of HTML strings.

Also applies to: 83-85, 92-94

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@extension/panel.js` around lines 68 - 70, The tree rendering in renderTree,
along with the related row builders at the other noted locations, is injecting
inspected-page values into the extension UI via innerHTML. Replace these HTML
string assignments with DOM node creation and textContent (or sanitize before
insertion) so node.tag, fmt(item), and e.label cannot inject markup into the
panel.

Source: Linters/SAST tools

src/devtools/bridge.ts-198-239 (1)

198-239: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Reject mismatched bridge protocol versions before dispatch.

handleMessage() currently accepts any v, so a v0/v2 panel can still drive the v1 server. That makes BRIDGE_PROTOCOL_VERSION informational instead of contractual and will fail open once the protocol evolves. Gate hello/request on data.v === BRIDGE_PROTOCOL_VERSION and fail fast on mismatches.

Patch sketch

   const handleMessage = (data: unknown): void => {
     if (!isInbound(data)) return;
+    if (data.v !== BRIDGE_PROTOCOL_VERSION) {
+      if (data.kind === 'request') {
+        options.post({
+          source: BRIDGE_SOURCE,
+          channel: 'page',
+          v: BRIDGE_PROTOCOL_VERSION,
+          kind: 'response',
+          id: data.id,
+          error: `Protocol mismatch: expected v${BRIDGE_PROTOCOL_VERSION}, received v${data.v}`,
+        });
+      }
+      return;
+    }
 
     if (data.kind === 'hello') {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/devtools/bridge.ts` around lines 198 - 239, handleMessage currently
dispatches every inbound message without enforcing the bridge version, so add a
strict check that data.v matches BRIDGE_PROTOCOL_VERSION before processing both
hello and request messages. If the version is missing or mismatched, reject the
message early by returning a response/error instead of calling announce() or
method(data.params), and keep the existing unknown-method and exception handling
paths unchanged. Use the handleMessage function and BRIDGE_PROTOCOL_VERSION as
the key entry points for the fix.