rip-lang 3.16.0 → 3.16.2

package/src/components.js

@@ -17,7 +17,13 @@ import { HTML_TAGS, SVG_TAGS, TEMPLATE_TAGS } from './generated/dom-tags.js';
 const BIND_PREFIX = '__bind_';
 const BIND_SUFFIX = '__';
 
-const LIFECYCLE_HOOKS = new Set(['beforeMount', 'mounted', 'updated', 'beforeUnmount', 'unmounted', 'onError']);
+const LIFECYCLE_HOOKS = new Set(['beforeMount', 'mounted', 'beforeUnmount', 'unmounted', 'onError']);
+
+// Canonical payload type for the onError lifecycle hook — the single source
+// of truth for both the optional declaration emitted when a component does
+// NOT define the hook and the shadow param type of a user-defined hook
+// whose param is unannotated.
+const ON_ERROR_PARAM_TYPE = '{ status?: number; message?: string; error?: Error; path?: string }';
 const BOOLEAN_ATTRS = new Set([
   'disabled', 'hidden', 'readonly', 'required', 'checked', 'selected',
   'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'multiple',
@@ -79,6 +85,84 @@ function getMemberType(target) {
   return null;
 }
 
+/**
+ * Extract `?` optionality flag from s-expression target node.
+ * Set by the lexer as `.optional` on the prop-name String wrapper when
+ * the source wrote `@label?:: T` or similar.
+ */
+function getMemberOptional(target) {
+  if (target instanceof String && target.optional) return true;
+  if (Array.isArray(target) && target[2] instanceof String && target[2].optional) return true;
+  return false;
+}
+
+/**
+ * Flatten a pure `.` chain s-expression into its segment names.
+ * `(. (. this app) data)` → ['this', 'app', 'data']. Returns null when the
+ * node isn't a plain identifier chain (computed access, calls, etc.).
+ */
+function chainSegments(node) {
+  const segs = [];
+  while (Array.isArray(node) && node[0] === '.') {
+    const prop = node[2];
+    if (!(typeof prop === 'string' || prop instanceof String)) return null;
+    segs.unshift(prop.valueOf());
+    node = node[1];
+  }
+  if (typeof node === 'string' || node instanceof String) segs.unshift(node.valueOf());
+  else return null;
+  return segs;
+}
+
+/**
+ * Parse a render gate's RHS (`user <~ @app.data.user`) into its hoistable
+ * parts. The RHS must be a literal `@app.data.…` chain, optionally applied
+ * to exactly one key argument (keyed source). Returns
+ * { path, keyExpr? } or { error }.
+ */
+function parseGatePath(rhs) {
+  let keyExpr;
+  let chain = rhs;
+  // Application form: [calleeChain, keyArg]
+  if (Array.isArray(rhs) && Array.isArray(rhs[0]) && rhs[0][0] === '.') {
+    if (rhs.length !== 2) return { error: 'a keyed gate takes exactly one key argument' };
+    chain = rhs[0];
+    keyExpr = rhs[1];
+  }
+  const segs = chainSegments(chain);
+  if (!segs) return { error: "'<~' requires a literal @app.data.… path on the right-hand side" };
+  if (segs[0] === 'this') segs.shift();
+  if (segs[0] !== 'app' || segs[1] !== 'data' || segs.length < 3) {
+    return { error: "'<~' requires a literal @app.data.… path on the right-hand side" };
+  }
+  return { path: segs.slice(2).join('.'), keyExpr };
+}
+
+/**
+ * Parse a keyed gate's key expression. The key must be available
+ * to the renderer before construction, so it is restricted to a literal or
+ * a params/query access (`params.id`, `@query.tab`). Returns
+ * { code, stubCode } (runtime and type-stub spellings) or { error }.
+ */
+function parseGateKey(expr) {
+  const KEY_ERROR = { error: 'a keyed gate key may only reference params or query (e.g. params.id)' };
+  const lit = (typeof expr === 'string' || expr instanceof String) ? expr.valueOf() : null;
+  if (lit != null) {
+    if (/^-?[\d.]/.test(lit) || lit.startsWith('"') || lit.startsWith("'")) {
+      return { code: lit, stubCode: lit };
+    }
+    return KEY_ERROR; // a bare identifier (incl. `params`/`query` alone) isn't a key
+  }
+  const segs = chainSegments(expr);
+  if (!segs) return KEY_ERROR;
+  if (segs[0] === 'this') segs.shift();
+  if ((segs[0] !== 'params' && segs[0] !== 'query') || segs.length < 2) return KEY_ERROR;
+  const code = segs.join('.');
+  // `params` and `query` are both Record<string, string> on the component, so
+  // the shadow reads the key the same way the runtime does — no cast needed.
+  return { code, stubCode: `this.${code}` };
+}
+
 // ============================================================================
 // Prototype Installation
 // ============================================================================
@@ -575,9 +659,52 @@ export function installComponentSupport(CodeEmitter, Lexer) {
   const _transferMeta = (from, to) => {
     if (!(from instanceof String)) return to;
     const s = new String(to);
-    if (from.predicate) s.predicate = true;
-    if (from.await) s.await = true;
-    return (s.predicate || s.await) ? s : to;
+    if (from.optional) s.optional = true;
+    if (from.bang) s.bang = true;
+    return (s.optional || s.bang) ? s : to;
+  };
+
+  // Inject `// @rip-src:N` markers onto each statement line of a method body
+  // emitted into a component stub.  The emitter doesn't carry source-map data
+  // for stub method bodies, so without explicit markers, typecheck.js falls
+  // back to linear gap-fill interpolation which silently misaligns when stub
+  // sizes change.  Walks the body s-expression to recover statement source
+  // lines and pairs them with the rendered body's non-trivial lines.
+  proto.addBodyRipSrcMarkers = function(bodyCode, bodySexpr) {
+    if (typeof bodyCode !== 'string' || !bodyCode) return bodyCode;
+    const stmts = Array.isArray(bodySexpr) && bodySexpr[0] === 'block'
+      ? bodySexpr.slice(1)
+      : (Array.isArray(bodySexpr) ? [bodySexpr] : []);
+    if (stmts.length === 0) return bodyCode;
+    const getLoc = (s) => {
+      if (s == null) return null;
+      if (!Array.isArray(s)) return s?.loc?.r ?? null;
+      if (s.loc?.r) return s.loc.r;
+      if (s[0]?.loc?.r) return s[0].loc.r;
+      for (const child of s) {
+        if (child?.loc?.r) return child.loc.r;
+        if (Array.isArray(child)) {
+          const l = getLoc(child);
+          if (l != null) return l;
+        }
+      }
+      return null;
+    };
+    const srcLines = stmts.map(getLoc);
+    if (srcLines.every(l => l == null)) return bodyCode;
+    const lines = bodyCode.split('\n');
+    let si = 0;
+    for (let i = 0; i < lines.length && si < srcLines.length; i++) {
+      const trimmed = lines[i].trim();
+      if (!trimmed) continue;
+      if (trimmed === '{' || trimmed === '}' || trimmed.startsWith('//')) continue;
+      if (lines[i].includes('@rip-src:')) { si++; continue; }
+      if (srcLines[si] != null) {
+        lines[i] = `${lines[i]} // @rip-src:${srcLines[si]}`;
+      }
+      si++;
+    }
+    return lines.join('\n');
   };
 
   proto.transformComponentMembers = function(sexpr, localScope = new Set()) {
@@ -676,6 +803,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     // Categorize statements
     const stateVars = [];
     const derivedVars = [];
+    const gateVars = [];
     const readonlyVars = [];
     const methods = [];
     const lifecycleHooks = [];
@@ -707,31 +835,51 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           reactiveMembers.add(varName);
         }
       } else if (op === '.' && stmt[1] === 'this' && getMemberName(stmt)) {
-        // Required prop: (. this name) — no default value
+        // Bare prop form: `(. this name)` — no default value.
+        // `@name`     → required (caller must pass)
+        // `@name?`    → optional (caller may omit; value will be undefined)
+        // `@name?:: T`→ optional, typed
         const varName = (typeof stmt[2] === 'string' || stmt[2] instanceof String) ? stmt[2].valueOf() : null;
         if (varName) {
-          stateVars.push({ name: varName, value: undefined, isPublic: true, type: stmt[2]?.type || null, required: true });
+          const optional = getMemberOptional(stmt);
+          stateVars.push({ name: varName, value: undefined, isPublic: true, type: stmt[2]?.type || null, required: !optional, optional, srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'state') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          stateVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]) });
+          stateVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]), optional: getMemberOptional(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'computed') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          derivedVars.push({ name: varName, expr: stmt[2], type: getMemberType(stmt[1]) });
+          derivedVars.push({ name: varName, expr: stmt[2], type: getMemberType(stmt[1]), srcLine: stmt.loc?.r });
+          memberNames.add(varName);
+          reactiveMembers.add(varName);
+        }
+      } else if (op === 'gate') {
+        // Render-ready binding: hoist the literal stash path into the
+        // component's static gate-set; bind the member as a reactive read.
+        const varName = getMemberName(stmt[1]);
+        if (varName) {
+          const parsed = parseGatePath(stmt[2]);
+          if (parsed.error) this.error(parsed.error, stmt);
+          let key = null;
+          if (parsed.keyExpr !== undefined) {
+            key = parseGateKey(parsed.keyExpr);
+            if (key.error) this.error(key.error, stmt);
+          }
+          gateVars.push({ name: varName, path: parsed.path, key, type: getMemberType(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'readonly') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          readonlyVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]) });
+          readonlyVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]), optional: getMemberOptional(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
         }
       } else if (op === '=') {
@@ -745,7 +893,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
               methods.push({ name: varName, func: val });
               memberNames.add(varName);
             } else {
-              stateVars.push({ name: varName, value: val, isPublic: isPublicProp(stmt[1]) });
+              stateVars.push({ name: varName, value: val, isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]), optional: getMemberOptional(stmt[1]), srcLine: stmt.loc?.r });
               memberNames.add(varName);
               reactiveMembers.add(varName);
             }
@@ -770,6 +918,17 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       }
     }
 
+    // Record gate declarations on the generator so the compile result can
+    // expose them (compiler.js threads `_gateDecls` through as `gates`).
+    // `rip check` validates each path against app/stash.rip's source-key
+    // set — the compile-time mirror of the renderer's mount check.
+    if (gateVars.length > 0) {
+      if (!this._gateDecls) this._gateDecls = [];
+      for (const { path, key, srcLine } of gateVars) {
+        this._gateDecls.push({ path, keyed: !!key, line: (srcLine ?? 0) + 1 });
+      }
+    }
+
     // Auto-event map: onClick → 'click', onKeydown → 'keydown', etc.
     const autoEventHandlers = new Map();
     for (const { name } of methods) {
@@ -804,28 +963,44 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
     // --- Type-check stub: typed member declarations + body expressions, no DOM ---
     if (this.options.stubComponents) {
-      // Inline type suffix expansion (mirrors types.js expandSuffixes)
-      const expandType = (t) => t ? t.replace(/::/g, ':')
-        .replace(/(\w+(?:<[^>]+>)?)\?\?/g, '$1 | null | undefined')
-        .replace(/(\w+(?:<[^>]+>)?)\?(?![.:])/g, '$1 | undefined')
-        .replace(/(\w+(?:<[^>]+>)?)\!/g, 'NonNullable<$1>') : null;
+      // Strip Rip's `::` annotation sigil to TypeScript's `:` separator.
+      const expandType = (t) => t ? t.replace(/::/g, ':') : null;
 
       const sl = [];
       const componentTypeParams = this._componentTypeParams || '';
       sl.push(`class ${componentTypeParams}{`);
-      // `declare app: any` is rewritten to a typed shape by typecheck.js when
-      // the project has a typed `<root>/app/stash.rip`. The compiler stays
-      // context-free; the rewrite happens in the same pass that splices
-      // function-overload signatures into the stub.
-      sl.push('  declare _root: Element | null; declare app: any;');
+      // Injected `this` shape for every component. The compiler stays
+      // context-free; `declare app: any` and `declare router: any` are
+      // rewritten by typecheck.js to typed shapes when the project anchor /
+      // stash file is discoverable. `params`, `query`, `children`, and the
+      // lifecycle hooks are stable across all projects, so they're typed
+      // here directly. User-defined hooks are emitted later as real methods;
+      // skip the optional-signature declaration for those names to avoid
+      // overload-optionality mismatches.
+      // Combine all injected declarations onto a single line to preserve the
+      // stub's prior line count.  Source-map gap-fill interpolates linearly
+      // between marker lines (e.g. between @rip-src markers from `@count`
+      // and a downstream method), so adding stub header lines pushes the
+      // method bodies past where interpolation expects them — breaking
+      // @ts-expect-error injection.  Keeping a single header line preserves
+      // the relative offsets.
+      sl.push('  declare _root: Element | null; declare app: any; declare router: any; declare params: Record<string, string>; declare query: Record<string, string>; declare children: any;');
+      const userHookNames = new Set(lifecycleHooks.map(h => h.name));
+      const hookDecls = [];
+      if (!userHookNames.has('beforeMount'))   hookDecls.push('beforeMount?(): void;');
+      if (!userHookNames.has('mounted'))       hookDecls.push('mounted?(): void;');
+      if (!userHookNames.has('beforeUnmount')) hookDecls.push('beforeUnmount?(): void;');
+      if (!userHookNames.has('unmounted'))     hookDecls.push('unmounted?(): void;');
+      if (!userHookNames.has('onError'))       hookDecls.push(`onError?(err: ${ON_ERROR_PARAM_TYPE}): void;`);
+      if (hookDecls.length) sl.push('  ' + hookDecls.join(' '));
       sl.push('  emit(_name: string, _detail?: any): void {}');
 
       // Constructor — typed props for public state/readonly (matches DTS)
       const propEntries = [];
-      for (const { name, type, isPublic, required } of stateVars) {
+      for (const { name, type, isPublic, required, optional } of stateVars) {
         if (!isPublic) continue;
         const ts = expandType(type);
-        const opt = required ? '' : '?';
+        const opt = (optional ?? !required) ? '?' : '';
         propEntries.push(`${name}${opt}: ${ts || 'any'}`);
         // Two-way binding: allow parent to pass Signal<T> for this prop
         propEntries.push(`__bind_${name}__?: Signal<${ts || 'any'}>`);
@@ -836,7 +1011,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         propEntries.push(`${name}?: ${ts || 'any'}`);
       }
       {
-        const hasRequired = propEntries.length > 0 && stateVars.some(v => v.isPublic && v.required);
+        const hasRequired = propEntries.length > 0 && stateVars.some(v => v.isPublic && v.required && !v.optional);
         const propsOpt = hasRequired ? '' : '?';
         let propsType = propEntries.length > 0 ? `{${propEntries.join('; ')}}` : '{}';
         if (inheritsTag) propsType += ` & __RipProps<'${inheritsTag}'>`;
@@ -853,10 +1028,55 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         return null;
       };
 
+      // A value references `this` synchronously if it reads `this`/`@…` or a
+      // reactive member (which emits as `this.x.value`) OUTSIDE any nested
+      // function. Refs inside a `->`/`=>` are deferred to call time, so they
+      // don't run during field initialization. Used below to decide whether a
+      // value is safe to emit as a field initializer (the injected `app`,
+      // `router`, … are `declare`-only, so a synchronous `this.app` read in a
+      // field initializer would trip TS2729 "used before initialization").
+      const refsThisSync = (node) => {
+        if (!Array.isArray(node)) {
+          if (typeof node === 'string' || node instanceof String) {
+            const s = node.valueOf();
+            return s === 'this' || reactiveMembers.has(s);
+          }
+          return false;
+        }
+        const head = node[0]?.valueOf?.() ?? node[0];
+        if (head === '->' || head === '=>') return false; // nested fn — deferred
+        return node.some(refsThisSync);
+      };
+
       // Property declarations (declare avoids definite-assignment errors)
-      for (const { name, type, value } of stateVars) {
+      const deferredStateInits = [];
+      for (const { name, type, value, isPublic, optional, srcLine } of stateVars) {
         const ts = expandType(type) || inferLiteralType(value);
-        sl.push(ts ? `  declare ${name}: Signal<${ts}>;` : `  declare ${name}: Signal<any>;`);
+        // Optional prop with no default: field can be undefined at runtime
+        // (we don't synthesize a `?? null` fallback below), so the Signal's
+        // payload type must include undefined.
+        // `?` widens the Signal payload to `| undefined` when the member has
+        // no initializer (`@label?:: T` — caller may omit) OR an explicit
+        // `:= undefined` (`x?:: T := undefined` — starts empty). A `?` with a
+        // real default stays `T`: the default fills the gap, so the field is
+        // never undefined.
+        const noValue = value === undefined || (value?.valueOf?.() ?? value) === 'undefined';
+        const optNoDefault = optional && noValue;
+        const wrapped = ts ? (optNoDefault ? `${ts} | undefined` : ts) : null;
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        // No declared or literal-inferred type, but a private initializer is
+        // present and reads nothing from `this` synchronously: emit a real
+        // field initializer (deferred below) so TS infers the Signal payload
+        // from the value — e.g. `x = createMutation(...)` → Signal<Mutation<R>>
+        // — instead of falling back to Signal<any>. Mirrors how computed/gate
+        // members already infer from their `__computed(...)` initializers.
+        // Values that touch `this` synchronously keep the declare form (they
+        // can't be field initializers — see refsThisSync above).
+        if (!wrapped && !isPublic && !noValue && !refsThisSync(value)) {
+          deferredStateInits.push({ name, value, marker });
+        } else {
+          sl.push((wrapped ? `  declare ${name}: Signal<${wrapped}>;` : `  declare ${name}: Signal<any>;`) + marker);
+        }
       }
       if (inheritsTag) {
         sl.push(`  declare rest: Signal<__RipProps<'${inheritsTag}'>>;`);
@@ -865,6 +1085,19 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         const ts = expandType(type) || inferLiteralType(value);
         sl.push(ts ? `  declare ${name}: ${ts};` : `  declare ${name}: any;`);
       }
+      // Gated bindings (<~): non-null by construction — the renderer loads
+      // the source before the component exists. __ripGate is the generic
+      // narrow `(v: T | null | undefined) => T`; soundness comes from the
+      // runtime gate, not from the type system proving the load ran.
+      for (const { name, path, key, type, srcLine } of gateVars) {
+        const ts = expandType(type);
+        const typeAnnot = ts ? `: Computed<${ts}>` : '';
+        const access = key
+          ? `this.app.data.${path}(${key.stubCode})`
+          : `this.app.data.${path}`;
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        sl.push(`  ${name}${typeAnnot} = __computed(() => __ripGate(${access}));` + marker);
+      }
       for (const { name, expr, type } of derivedVars) {
         const ts = expandType(type);
         const typeAnnot = ts ? `: Computed<${ts}>` : '';
@@ -878,21 +1111,31 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         }
       }
 
+      // Inferred-type private state vars: field initializers emitted after the
+      // computed members above, so any member they read is already declared.
+      for (const { name, value, marker } of deferredStateInits) {
+        const val = this.emitInComponent(value, 'value');
+        sl.push(`  ${name} = __state(${val});` + marker);
+      }
+
       // _init body — readonly, state, computed assignments (skip accepted/offered)
       sl.push('  _init(props) {');
-      for (const { name, value, isPublic } of readonlyVars) {
+      for (const { name, value, isPublic, srcLine } of readonlyVars) {
         const val = this.emitInComponent(value, 'value');
-        sl.push(isPublic ? `    this.${name} = props.${name} ?? ${val};` : `    this.${name} = ${val};`);
-      }
-      for (const { name, value, isPublic, required, type } of stateVars) {
-        if (isPublic && required) {
-          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});`);
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        sl.push((isPublic ? `    this.${name} = props.${name} ?? ${val};` : `    this.${name} = ${val};`) + marker);
+      }
+      for (const { name, value, isPublic, required, type, srcLine } of stateVars) {
+        if (deferredStateInits.some(d => d.name === name)) continue;
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        if (isPublic && (required || value === undefined)) {
+          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});` + marker);
         } else if (isPublic) {
           const val = this.emitInComponent(value, 'value');
-          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name} ?? ${val});`);
+          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name} ?? ${val});` + marker);
         } else {
           const val = this.emitInComponent(value, 'value');
-          sl.push(`    this.${name} = __state(${val});`);
+          sl.push(`    this.${name} = __state(${val});` + marker);
         }
       }
 
@@ -976,7 +1219,12 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           }
           const transformed = this.reactiveMembers ? this.transformComponentMembers(methodBody) : methodBody;
           const isAsync = this.containsAwait(methodBody);
-          const bodyCode = this.emitFunctionBody(transformed, params || []);
+          let bodyCode = this.emitFunctionBody(transformed, params || []);
+          // Inject @rip-src markers on each body statement line so that
+          // @ts-expect-error injection and hover/diagnostics resolve to the
+          // user's actual source line, instead of relying on linear gap-fill
+          // interpolation across the stub (which is brittle to stub size).
+          bodyCode = this.addBodyRipSrcMarkers(bodyCode, methodBody);
           sl.push(`  ${isAsync ? 'async ' : ''}${name}(${paramStr}) ${bodyCode}`);
         }
       }
@@ -985,10 +1233,26 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       for (const { name, value } of lifecycleHooks) {
         if (Array.isArray(value) && (value[0] === '->' || value[0] === '=>')) {
           const [, params, hookBody] = value;
-          const paramStr = Array.isArray(params) ? params.map(p => this.formatParam(p)).join(', ') : '';
+          let paramStr = Array.isArray(params) ? params.map(p => this.formatParam(p)).join(', ') : '';
+          // onError's payload shape is known to the framework, but its typed
+          // optional declaration above is only emitted when the user does
+          // NOT define the hook (a real method would collide with it) — so a
+          // user-defined `onError: (err) ->` has no signature to inherit
+          // from, and an unannotated param would be an implicit any in
+          // strict projects. Type it from the same canonical constant the
+          // declaration uses. Detection is structural (the parse tree's
+          // type metadata, like getMemberType), and an explicit user
+          // annotation always wins.
+          if (name === 'onError' && Array.isArray(params) && params.length === 1) {
+            const p = params[0];
+            if ((typeof p === 'string' || p instanceof String) && !meta(p, 'type')) {
+              paramStr = `${p.valueOf()}: ${ON_ERROR_PARAM_TYPE}`;
+            }
+          }
           const transformed = this.reactiveMembers ? this.transformComponentMembers(hookBody) : hookBody;
           const isAsync = this.containsAwait(hookBody);
-          const bodyCode = this.emitFunctionBody(transformed, params || []);
+          let bodyCode = this.emitFunctionBody(transformed, params || []);
+          bodyCode = this.addBodyRipSrcMarkers(bodyCode, hookBody);
           sl.push(`  ${isAsync ? 'async ' : ''}${name}(${paramStr}) ${bodyCode}`);
         }
       }
@@ -999,6 +1263,18 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         const constructions = [];
         let constructionIdx = 0;
         const sourceLines = this.options.source?.split('\n');
+        // Route-check any `href:` prop passed to a component the same way
+        // intrinsic `<a href>` is checked. A component that forwards href to
+        // an anchor (e.g. `component extends a`) exposes it via `@rest` typed
+        // as plain `string`, so without this `ButtonLink href: "/typo"` would
+        // escape route validation entirely. We can't see the component's tag
+        // cross-module, so we key on the prop name — `href` is a URL wherever
+        // it appears. Wrap slash-prefixed string and template literals in
+        // `__ripRoute(...)` (strengthened to the route union when the project
+        // has routes); external URLs and variables (no leading-slash literal)
+        // pass through untouched.
+        const wrapCompHref = (val) =>
+          typeof val === 'string' && /^["'`]\//.test(val) ? `__ripRoute(${val})` : val;
         const extractProps = (args) => {
           const props = [];
           const sideExprs = [];
@@ -1042,7 +1318,8 @@ export function installComponentSupport(CodeEmitter, Lexer) {
                     props.push({ code: `${key}: ${member}`, srcLine });
                   } else {
                     const val = this.emitInComponent(value, 'value');
-                    props.push({ code: `${key}: ${val}`, srcLine });
+                    const finalVal = key === 'href' ? wrapCompHref(val) : val;
+                    props.push({ code: `${key}: ${finalVal}`, srcLine });
                   }
                 }
               }
@@ -1051,8 +1328,22 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           props.sideExprs = sideExprs;
           return props;
         };
-        const extractIntrinsicProps = (args) => {
+        const extractIntrinsicProps = (args, tagName) => {
           const props = [];
+          // For <a href: ...>, wrap interpolated route literals (templates
+          // starting with `/...`) in __ripRoute so TS checks the dynamic
+          // template against __RipRoutes. Static literals fall through to
+          // the existing __ripEl Option-C conditional, which still gives
+          // the "Did you mean ..." hint. Variables and external URLs are
+          // left untouched.
+          const wrapHrefVal = (val) => {
+            if (tagName !== 'a') return val;
+            if (typeof val !== 'string') return val;
+            if (val.length < 2) return val;
+            if (val[0] !== '`') return val;
+            if (val[1] !== '/') return val;
+            return `__ripRoute(${val})`;
+          };
           for (const arg of args) {
             let obj = null;
             if (this.is(arg, 'object')) {
@@ -1071,9 +1362,25 @@ export function installComponentSupport(CodeEmitter, Lexer) {
                 if (Array.isArray(key) && key[0] === '.' && key[1] === 'this') {
                   let memberName = typeof key[2] === 'string' ? key[2] : key[2]?.valueOf?.();
                   if (!memberName) continue;
-                  const eventKey = '@' + memberName.split('.')[0];
-                  const val = this.emitInComponent(value, 'value');
-                  props.push({ code: `'${eventKey}': ${val}`, srcLine });
+                  const eventName = memberName.split('.')[0];
+                  let val = this.emitInComponent(value, 'value');
+                  // Inline arrow handler: explicitly annotate its untyped first
+                  // param with the event type. Letting TS contextually type it
+                  // through __ripEl's generic props is fragile — certain prop
+                  // combinations silently drop the param to `any`. This gives
+                  // inline handlers the same reliable typing the `@event: @method`
+                  // path already gets, matching __RipEvents' shape exactly.
+                  if (Array.isArray(value) && (value[0] === '->' || value[0] === '=>')) {
+                    const p0 = value[1]?.[0];
+                    const pName = typeof p0 === 'string' ? p0 : p0?.valueOf?.();
+                    if (pName && !(p0 && p0.type) && /^[A-Za-z_$][\w$]*$/.test(pName)) {
+                      const T = `RipEvent<HTMLElementEventMap['${eventName}'], __RipElementMap['${tagName}']>`;
+                      val = val[0] === '('
+                        ? val.replace(new RegExp('^\\(\\s*' + pName + '\\b'), `(${pName}: ${T}`)
+                        : val.replace(new RegExp('^' + pName + '\\b'), `(${pName}: ${T})`);
+                    }
+                  }
+                  props.push({ code: `'@${eventName}': ${val}`, srcLine });
                 } else if (typeof key === 'string') {
                   if (key === 'key') {
                     // key: is not an HTML attribute, but emit its value
@@ -1089,7 +1396,8 @@ export function installComponentSupport(CodeEmitter, Lexer) {
                     props.push({ code: `${propName}: ${val}`, srcLine });
                   } else {
                     const val = this.emitInComponent(value, 'value');
-                    props.push({ code: `${key}: ${val}`, srcLine });
+                    const finalVal = key === 'href' ? wrapHrefVal(val) : val;
+                    props.push({ code: `${key}: ${finalVal}`, srcLine });
                   }
                 }
               }
@@ -1166,14 +1474,38 @@ export function installComponentSupport(CodeEmitter, Lexer) {
               const condCode = this.emitInComponent(condition, 'value');
               const srcLine = node.loc?.r;
               const srcMarker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
-              constructions.push(`    ${condCode};${srcMarker}`);
+              // Emit a real `if (...) { } else { }` (mirroring the for-loop
+              // case below) instead of a bare condition statement with the
+              // branches flattened as unguarded siblings. The structure is
+              // what lets TS narrow the condition inside the then-branch —
+              // `if order then order.total` type-checks against `T | null`
+              // without `?.` laundering. Reads are plain property chains
+              // (`this.order.value`), which TS keeps narrowed across the
+              // intervening `__ripEl(...)` stub calls.
+              const guard = head === 'unless' ? `!(${condCode})` : condCode;
+              constructions.push(`    if (${guard}) {${srcMarker}`);
+              if (node[2] != null) walkRender(node[2]);
+              const elses = node.slice(3).filter(n => n != null);
+              if (elses.length) {
+                constructions.push(`    } else {`);
+                for (const e of elses) walkRender(e);
+              }
+              constructions.push(`    }`);
+              return; // branches fully handled — don't re-walk children below
             }
           } else if (head === '?:') {
-            // Emit the full ternary so all branches are type-checked
+            // Emit the full ternary so all branches are type-checked, then
+            // return — like the `__text__`/`str` cases. The emitted expression
+            // already covers every branch, so re-walking children is redundant
+            // and actively harmful: a nested member access (e.g. `opt.label`
+            // in `typeof opt is "string" ? opt : opt.label`) would hit the
+            // bare member-access case below and be re-emitted *unguarded*,
+            // stripping the `typeof` narrowing and producing a false error.
             const ternCode = this.emitInComponent(node, 'value');
             const srcLine = node.loc?.r;
             const srcMarker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
             constructions.push(`    ${ternCode};${srcMarker}`);
+            return;
           } else if (head === 'switch') {
             const discriminant = node[1];
             if (discriminant != null) {
@@ -1242,6 +1574,26 @@ export function installComponentSupport(CodeEmitter, Lexer) {
               constructions.push(`    ${exprCode};${srcMarker}`);
             } catch {}
             return;
+          } else if (head === '.' || head === '?.') {
+            // Bare member-access expression as element content
+            // (e.g. `div config.site.theme.logoMark`). Walk to the chain's
+            // base identifier: emit it for type-checking only when the base
+            // is a value reference, NOT an HTML tag-shorthand like `div.image`
+            // (whose base IS a tag). Without this, static text-content
+            // expressions never reach the stub and escape type-checking —
+            // only interpolated "#{...}" content was being checked.
+            let base = node;
+            while (Array.isArray(base) && (base[0] === '.' || base[0] === '?.')) base = base[1];
+            const baseName = typeof base === 'string' ? base : base?.valueOf?.();
+            if (typeof baseName === 'string' && !this.isHtmlTag(baseName) && !CodeEmitter.GENERATORS[baseName]) {
+              try {
+                const exprCode = this.emitInComponent(node, 'value');
+                const srcLine = node.loc?.r;
+                const srcMarker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+                constructions.push(`    ${exprCode};${srcMarker}`);
+              } catch {}
+            }
+            return;
           }
 
           // Emit a bare lowercase identifier as either a property access
@@ -1373,7 +1725,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           } else if (typeof head === 'string' && !CodeEmitter.GENERATORS[head] && (TEMPLATE_TAGS.has(head.split(/[.#]/)[0]) ||
                      (/^[a-z][\w-]*$/.test(head) && node.length > 1))) {
             const tagName = head.split(/[.#]/)[0];
-            const iProps = extractIntrinsicProps(node.slice(1));
+            const iProps = extractIntrinsicProps(node.slice(1), tagName);
             const tagLine = node.loc?.r;
             const srcMarker = tagLine != null ? ` // @rip-src:${tagLine}` : '';
             if (iProps.length === 0) {
@@ -1423,9 +1775,28 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
     lines.push('class extends __Component {');
 
+    // Static gate-set — readable by the renderer without
+    // constructing the component. Strings are plain stash paths; keyed
+    // gates carry a key fn the renderer evaluates with the matched
+    // params/query before construction.
+    if (gateVars.length > 0) {
+      const items = gateVars.map(({ path, key }) => key
+        ? `{ path: '${path}', key: (params, query) => ${key.code} }`
+        : `'${path}'`);
+      lines.push(`  static __gates = [${items.join(', ')}];`);
+    }
+
     // --- Init (called by __Component constructor) ---
     lines.push('  _init(props) {');
 
+    // Gated bindings (<~) — first, so any readonly/state initializer can
+    // consume the loaded value synchronously (`form := { ...user }`).
+    for (const { name, path, key } of gateVars) {
+      lines.push(key
+        ? `    this.${name} = __gateBind(this, '${path}', (params, query) => ${key.code});`
+        : `    this.${name} = __gateBind(this, '${path}');`);
+    }
+
     // Constants (readonly)
     for (const { name, value, isPublic } of readonlyVars) {
       const val = this.emitInComponent(value, 'value');
@@ -1441,7 +1812,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
     // State variables (__state handles signal passthrough)
     for (const { name, value, isPublic, required } of stateVars) {
-      if (isPublic && required) {
+      if (isPublic && (required || value === undefined)) {
         lines.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});`);
       } else if (isPublic) {
         const val = this.emitInComponent(value, 'value');
@@ -2727,7 +3098,13 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     const outerParams = this._loopVarStack.map(v => `${v.itemVar}, ${v.indexVar}`).join(', ');
     const outerExtra = outerParams ? `, ${outerParams}` : '';
 
-    this._loopVarStack.push({ itemVar, indexVar });
+    // If the iterated collection is reactive, treat direct member access
+    // on the iter var (`item.qty`, `item[0]`, `item.a.b`) as reactive
+    // inside the loop body. hasReactiveDeps consults this flag, so the
+    // existing emit paths wrap those reads in __effect and the per-row
+    // patch function gets populated.
+    const reactiveSource = this.hasReactiveDeps(collection);
+    this._loopVarStack.push({ itemVar, indexVar, reactiveSource });
     const itemNode = this.emitTemplateBlock(body);
     this._loopVarStack.pop();
     const itemCreateLines = this._createLines;
@@ -3037,6 +3414,16 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       return true;
     }
 
+    // Property chain rooted at a `for`-loop iter var whose source is
+    // reactive (e.g. `for item in cart.items` → `item.qty`, `item[0]`,
+    // `item.foo.bar`). Same rationale as the this-rooted case: the source
+    // proxy is reactive at runtime, so any member read may track. Limited
+    // to direct member access on the iter var — aliases and destructuring
+    // are explicitly out of scope.
+    if ((sexpr[0] === '.' || sexpr[0] === '[]') && this._rootsAtReactiveLoopVar(sexpr)) {
+      return true;
+    }
+
     // Method call on component: [['.', 'this', method], ...args]
     // Methods may read reactive state internally — treat as reactive so the
     // call gets wrapped in __effect and re-runs when dependencies change.
@@ -3118,6 +3505,26 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     return this._rootsAtThis(sexpr[1]);
   };
 
+  // _rootsAtReactiveLoopVar — true when a `.` / `[]` access chain bottoms
+  // out at a string identifier that matches the itemVar of some frame on
+  // _loopVarStack whose `reactiveSource` is true. See emitTemplateLoop.
+  proto._rootsAtReactiveLoopVar = function(sexpr) {
+    if (typeof sexpr === 'string') {
+      if (!this._loopVarStack || this._loopVarStack.length === 0) return false;
+      // Iterate innermost-first so a shadowed name resolves to its nearest
+      // binding: `for item in reactive` containing `for item in [1,2,3]`
+      // must treat inner reads of `item` as non-reactive.
+      for (let i = this._loopVarStack.length - 1; i >= 0; i--) {
+        const v = this._loopVarStack[i];
+        if (v.itemVar === sexpr) return !!v.reactiveSource;
+      }
+      return false;
+    }
+    if (!Array.isArray(sexpr)) return false;
+    if (sexpr[0] === '.' || sexpr[0] === '[]') return this._rootsAtReactiveLoopVar(sexpr[1]);
+    return false;
+  };
+
   // ==========================================================================
   // Component Runtime
   // ==========================================================================
@@ -3387,6 +3794,28 @@ function __transition(el, name, dir, done) {
   });
 }
 
+// Render-ready binding (\`x <~ @app.data.x\`): a reactive read of a
+// stash source key that retains the last non-null value for the life of
+// this instance. A null write or reset() invalidates the CELL (ungated
+// readers see it immediately) without yanking mounted gates — the
+// live-binding invariant. Last-good lives in this closure, so it dies
+// with the instance.
+function __gateBind(self, path, keyFn) {
+  // The component runtime ships both inlined after the reactive runtime
+  // (where __computed is a local) and as a standalone bundle chunk (where
+  // it is not) — resolve through globalThis.__rip in the latter case.
+  const __c = typeof __computed !== 'undefined' ? __computed : globalThis.__rip.__computed;
+  let last;
+  return __c(() => {
+    const data = self.app && self.app.data;
+    if (!data) return last;
+    const v = keyFn
+      ? data[path](keyFn(self.params || {}, self.query || {}))
+      : data[path];   // dotted paths route through the stash's path-key get
+    return v != null ? (last = v) : last;
+  });
+}
+
 function __handleComponentError(error, component) {
   let current = component;
   // Defensive cycle guard: if the parent chain is corrupted (e.g. by
@@ -3408,6 +3837,17 @@ class __Component {
   constructor(props = {}) {
     Object.assign(this, props);
     if (!this.app && globalThis.__ripApp) this.app = globalThis.__ripApp;
+    // A component with render gates (<~) is honored only via route
+    // matching — the renderer sets __ripGateMount around each route/layout
+    // construction. Constructed as an embedded child (a parent scope is
+    // active but the renderer flag doesn't match), its gates were never
+    // loaded, so the T-typed bindings would be silent nulls. Fail loud and
+    // deterministically instead. Direct construction outside any component
+    // scope (tests: seed the stash, then construct) stays allowed.
+    const __g = this.constructor.__gates;
+    if (__g && __g.length && globalThis.__ripGateMount !== this.constructor && __currentComponent) {
+      throw new Error('[Rip] component declares render gates (<~) but was constructed as an embedded child; gates are honored only via route matching — lift the gate to the route/layout and pass the value as a prop');
+    }
     const prev = __pushComponent(this);
     try {
       this._init(props);
@@ -3507,7 +3947,7 @@ class __Component {
 
 // Register on globalThis for runtime deduplication
 if (typeof globalThis !== 'undefined') {
-  globalThis.__ripComponent = { __pushComponent, __popComponent, __getCurrentComponent, setContext, getContext, hasContext, __clsx, __lis, __reconcile, __transition, __handleComponentError, __Component };
+  globalThis.__ripComponent = { __pushComponent, __popComponent, __getCurrentComponent, setContext, getContext, hasContext, __clsx, __lis, __reconcile, __transition, __handleComponentError, __gateBind, __Component };
 }
 
 `;