rip-lang 3.16.1 → 3.16.2

package/src/components.js

@@ -18,6 +18,12 @@ const BIND_PREFIX = '__bind_';
 const BIND_SUFFIX = '__';
 
 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',
@@ -90,6 +96,73 @@ function getMemberOptional(target) {
   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
 // ============================================================================
@@ -730,6 +803,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     // Categorize statements
     const stateVars = [];
     const derivedVars = [];
+    const gateVars = [];
     const readonlyVars = [];
     const methods = [];
     const lifecycleHooks = [];
@@ -786,6 +860,22 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           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) {
@@ -803,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]), srcLine: stmt.loc?.r });
+              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);
             }
@@ -828,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) {
@@ -883,14 +984,14 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       // 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: URLSearchParams; declare children: any;');
+      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: { status?: number; message?: string; error?: Error; path?: string }): 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 {}');
 
@@ -927,16 +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, optional, srcLine } of stateVars) {
+      const deferredStateInits = [];
+      for (const { name, type, value, isPublic, optional, srcLine } of stateVars) {
         const ts = expandType(type) || inferLiteralType(value);
         // 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.
-        const optNoDefault = optional && value === 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}` : '';
-        sl.push((wrapped ? `  declare ${name}: Signal<${wrapped}>;` : `  declare ${name}: Signal<any>;`) + marker);
+        // 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}'>>;`);
@@ -945,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}>` : '';
@@ -958,6 +1111,13 @@ 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, srcLine } of readonlyVars) {
@@ -966,6 +1126,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         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);
@@ -1072,7 +1233,22 @@ 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);
           let bodyCode = this.emitFunctionBody(transformed, params || []);
@@ -1087,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 = [];
@@ -1130,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 });
                   }
                 }
               }
@@ -1173,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
@@ -1269,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) {
@@ -1345,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
@@ -1526,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');
@@ -3526,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
@@ -3547,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);
@@ -3646,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 };
 }
 
 `;

package/src/dts.js

@@ -83,7 +83,7 @@ export function ripDestructuredNames(source) {
 // emitTypes — generate .d.ts from annotated tokens + s-expression tree
 // ============================================================================
 
-export function emitTypes(tokens, sexpr = null, source = '') {
+export function emitTypes(tokens, sexpr = null, source = '', schemaBehavior = null, schemaAnon = null) {
   let lines = [];
   let indentLevel = 0;
   let indentStr = '  ';
@@ -797,6 +797,12 @@ export function emitTypes(tokens, sexpr = null, source = '') {
           lines.push(`${indent()}${exp}${declare}const ${varName}: Computed<${type}>;`);
         } else if (next[0] === 'EFFECT') {
           lines.push(`${indent()}${exp}${declare}const ${varName}: () => void;`);
+        } else if (next[0] === 'GATE') {
+          // Render-ready gate (<~) — only valid inside component
+          // bodies, where the component stub (not this hoist) types the
+          // binding. Explicit no-op so an annotated gate never falls
+          // through to the `=` arrow-scan below.
+          continue;
         } else if (next[0] === '=') {
           // Check if RHS is an arrow function with return type
           let arrowIdx = i + 2;
@@ -821,7 +827,16 @@ export function emitTypes(tokens, sexpr = null, source = '') {
           } else if (inClass) {
             lines.push(`${indent()}${varName}: ${type};`);
             classFields.add(varName);
-          } else {
+          } else if (bodyDepth === 0) {
+            // Module-scope typed binding: typecheck.js's inline-let pass
+            // merges this header line into the body's hoist by NAME. That
+            // name-based merge is only sound at module scope — for a
+            // function-local (`bodyDepth > 0`) the same name can exist
+            // untyped in sibling functions, and the merge would stamp this
+            // annotation onto every one of them. Function-locals don't
+            // need the header line anyway: the compiler's typed-local
+            // hoist (collectTypedLocals) annotates the owning function's
+            // own `let` in the body, scope-correctly.
             lines.push(`${indent()}${exp}let ${varName}: ${type};`);
           }
         } else if (inClass) {
@@ -852,7 +867,7 @@ export function emitTypes(tokens, sexpr = null, source = '') {
     // Schema declarations — strip any prior auto-emitted `declare let Foo`
     // for the same bindings (they are re-emitted as typed Schema<T>).
     let schemaLines = [];
-    hasSchemaDecls = emitSchemaTypes(sexpr, schemaLines);
+    hasSchemaDecls = emitSchemaTypes(sexpr, schemaLines, schemaBehavior, schemaAnon);
     if (hasSchemaDecls) {
       let bindings = new Set();
       for (let line of schemaLines) {