From e2e73ea27a54bb323a1878274781e8883336ff88 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 13:49:41 -0800 Subject: [PATCH 1/5] docs(api): ref inputs end in Ref; API review matches each new name to the system; props live in the contracts package --- docs/architecture/public-component-api.md | 73 ++++++++++++++++++- .../AST-082-native-first-surfaces/spec.md | 23 ++++++ 2 files changed, 95 insertions(+), 1 deletion(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 6d3ff5868cbeb..ce99a8d8d0304 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -120,7 +120,7 @@ guidance owns the process used to propose and test APIs. `springs.contextMenuLift`, so it does not name a layout distance. An element ref a hook takes is named for the element's job, as `containerRef`, `scrollRef`, `menuRef`, `triggerRef`, and `inputRef` are, or `ref` when the element has - no narrower job. + no narrower job (INV29). - **INV3 — One prop controls one independent concept.** A prop does not silently suppress an unrelated prop. A parent does not duplicate state already owned by a composed child. One interaction behavior is one prop, never parallel touch, @@ -330,6 +330,39 @@ guidance owns the process used to propose and test APIs. including a reachable member tagged internal, goes to human review with that row listed, for an owner of this record, as `architecture:knowledge-contracts` change coupling step 6 describes. A removed or renamed row follows INV9. +- **INV29 — A ref input ends in `Ref`.** A public prop or hook option whose + value is a React ref has a name that ends in `Ref`. Its type is + `RefObject`, or `Ref` when it also accepts a callback ref + (INV8). It does not take a bare element, and it does not take a function + that returns an element, alone or in a union with a ref. A ref that a hook + returns for the caller to attach also ends in `Ref` and has the type + `RefCallback` or `RefObject`, as `usePopover`'s `triggerRef` + and `useHoverCard`'s `positionRef` do. A name that ends in `Ref` holds a ref + and nothing else. A function that computes an element from its arguments, + such as `useGridFocus`'s `getFocusTarget(cell)`, is a callback, not an + element input. A prop that names the same role as an existing prop uses + that prop's name and wording: the element a layer sits on is `anchorRef`, + as on Tooltip, Popover, and BaseTypeahead; the element that opens a layer + is `triggerRef`, as on `useMenuPress` and `useTouchTrigger`; and an + imperative handle is `handleRef`, as on Calendar, Carousel, and + ComplexSelector. A ref is React-only: a core contract states the need in + platform-neutral words, and the React contract maps it to a `…Ref` prop + (`spec:AST-082` FR4). A `create…` equivalent (INV22) keeps the option's + name and takes any object with a `current` element, so code outside React + can pass one. A shipped input that breaks this rule changes only under INV9 + and INV21a. +- **INV30 — Public-API review holds each new name to the system.** For each + added or changed row of a pull request's API delta (INV24), public-API + review finds the components and hooks that already have a prop, option, or + return member for the same role. It searches by the role's words and by + the type, not only by the new name. It compares the row with those + members, with INV2, INV29, and DEC-1, and with + [API conventions](../contributing/api-conventions.md). It raises each + mismatch in name, wording, type, default, or meaning as a finding, names + the existing member that the row must match, and does not mark a mismatch + as optional. A row that matches no existing role states that it found + none. A new prop that the component can replace with a better default + behavior is a finding (INV4, `spec:AST-082` FR3). This record applies to stable public packages, and INV23 also applies to Lab source. Lab components are not stable public promises until promotion. @@ -456,6 +489,37 @@ The owner said: "okay let's get rid of this massive file. We don't need it, we s Rejected: keeping a committed generated API report per package. +### DEC-8 — Ref inputs end in `Ref` and take only a ref + +**Reference:** `architecture:public-component-api/DEC-8` +**Decider:** `cixzhang`, `2026-11-18 13:28 PT` + +The owner said: "all refs should be postfixed with Ref and we should add that +to the API consistency spec, these ref props are also not available outside +of react", and, on `usePopover`'s anchor: "so it should be anchorRef to +match, I think we have patterns like this in hovercard/tooltip? Match the +language". A `Ref` suffix tells a caller the input wants a ref before they +read its type. One name per role lets a caller who knows Tooltip's +`anchorRef` find Popover's and `usePopover`'s. A ref is React-only, so the +core contract states the need without one (`spec:AST-082` FR4). + +Rejected: an input that takes a ref or a getter, because the name cannot say +both and the getter has no form outside React either; and a new name for a +role that an existing input already names. + +### DEC-9 — Public-API review searches for the same role and raises every mismatch + +**Reference:** `architecture:public-component-api/DEC-9` +**Decider:** `cixzhang`, `2026-11-18 13:34 PT` + +The owner said: "when we have codebunny review API updates, we should hold a +high bar for API consistency, it should search for related components and +refer to API naming conventions spec. Then raise where we don't match". A +public prop is permanent once it ships (INV9), so review catches a mismatch +before it ships, when a rename costs nothing. + +Rejected: reviewing a new name only against its own component. + ## Verification | Invariant | Evidence | Failure signal | @@ -481,6 +545,8 @@ Rejected: keeping a committed generated API report per package. | INV23 | `@astryx/no-raw-private-attribute` lint with its baseline (test files exempt), plus public-API review of the public list | A `data-astryx-*` name or selector written outside its owner module, a test, or the public list; a `dataAttr()` call that names a private attribute; an owner module that exports its raw name or a selector; a package that imports another package's owner module; a caller that sets a property an owner style it spreads also sets; a private attribute in a public export, `.doc.mjs`, or Changeset; a baseline entry added; a public data attribute changed without INV9 evidence | | INV24 | Generator tests, CI's merge-base-to-head surface compare, and the review bot's per-PR API delta | A promised export, prop, hook, type, custom property, theme target, public attribute, or event is missing from the delta; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; the merge gate passes a pull request that changes a published package when the compare artifact is missing or the generator errors; the review bot's summary notes do not start with the delta or "New public API: none"; a delta row decides acceptance | | INV25 | Public-API review routing against the pull request's API delta | A row that no current record decides does not reach human review; a row a current record decides is held for a human; an undeclared row alone draws a request for changes | +| INV29 | Public-API review of the generated declaration inventory (INV24); a lint rule is a known gap | A public prop, hook option, or returned ref that holds a React ref and does not end in `Ref`; a `…Ref` member whose type is not a ref; a ref input that also accepts a bare element or a getter; a new input for a role that an existing input already names, under a different name or wording | +| INV30 | The review bot's API delta notes and its findings on the pull request | A delta row with no search for existing members of the same role; a mismatch with an existing member, INV2, INV29, DEC-1, or the API conventions that review does not raise; a mismatch marked optional | | Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices | Known verification gaps: @@ -526,6 +592,11 @@ Known verification gaps: and has no `create…` factory yet; no full inventory exists yet. Each conforms by adding its factory; a shipped hook's signature changes only when a real need arises (INV21a). +- INV29 gap: no lint rule checks the `Ref` suffix or the ref type yet. + Public-API review is the only check. Three shipped inputs break the rule: + `useMenuPress`'s `getScroller` and `useLayerDismissal`'s `getContainer` take + a getter, and Lab ChatVirtualizer's `scrollElement` takes an element. + INV21a keeps the two shipped hook options until a real need arises. - The passthrough lint is warning-only while known violations remain. - The current source-to-doc completeness matcher still looks for old prefixed props interfaces, so it does not yet prove full prop coverage. diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index e6e13bc3e2b0e..6b5c2ba10eb71 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -107,6 +107,12 @@ depends only on runtimes it can maintain. prop. Moving a released prop from the core to the web contract changes no web caller's types, because the web types are the core contract plus the web contract; native contracts stop offering it. + - Every public prop is defined in the private contracts package, which each + package builds in. Astryx manages each prop there for every surface at + once. A new prop is a permanent part of every contract that carries it, so + admitting one is a high bar (`spec:AST-002/DEC-1`): when a better default + behavior meets the need, the component changes its default and adds no + prop. - The web contract holds the web base props: styling inputs, DOM events, refs, element choice, and HTML attributes. - A component may exist on some platforms only; using it elsewhere fails at @@ -149,6 +155,10 @@ depends only on runtimes it can maintain. components. A platform contract may accept a wider form for the same slot, such as a React node on the web; the slot keeps one meaning, and the core form is what every native platform accepts. + - A React ref is not portable. A core contract states the need in neutral + words, such as "the element the popover anchors to", and each platform's + contract maps it: on React, a `…Ref` prop + (`architecture:public-component-api` INV29). - **FR5 — Platform props are platform-scoped types.** `@astryxdesign/core` exposes the core contracts and the web contracts; its default types are the web contracts, unchanged for web callers. `@astryxdesign/native` exposes the native @@ -706,6 +716,19 @@ it once as durable intent rather than repeating it in each platform's entry. Rejected: iOS platform-entry terms only, because every other native platform would need the same words again. +### DEC-17 — Props live in the contracts package, and a new prop is a high bar + +**Reference:** `spec:AST-082/DEC-17` +**Decider:** `cixzhang`, `2026-11-18 13:35 PT` + +The owner said: "we should be wary of adding new props in general since they +become permanent additions to our contract. Once we put contract into a +separate lib, we should move all props there and they will be centrally +managed and considered across all surfaces". One home for every prop lets a +new prop be judged against every surface before it ships. + +Rejected: props defined in each package and reconciled later. + ## Open questions - **OQ1 — What thresholds make a candidate supported?** (`human-design`) From 4b49337eddc8b41621d39c87b2a832c726a195be Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 13:50:10 -0800 Subject: [PATCH 2/5] docs(api): the INV29 gap line states the gap, not a status --- docs/architecture/public-component-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index ce99a8d8d0304..1a657dbaefd96 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -592,8 +592,8 @@ Known verification gaps: and has no `create…` factory yet; no full inventory exists yet. Each conforms by adding its factory; a shipped hook's signature changes only when a real need arises (INV21a). -- INV29 gap: no lint rule checks the `Ref` suffix or the ref type yet. - Public-API review is the only check. Three shipped inputs break the rule: +- INV29 gap: no lint rule checks the `Ref` suffix or the ref type; + public-API review is the only check. Three shipped inputs break the rule: `useMenuPress`'s `getScroller` and `useLayerDismissal`'s `getContainer` take a getter, and Lab ChatVirtualizer's `scrollElement` takes an element. INV21a keeps the two shipped hook options until a real need arises. From 1dcfc2871aaeb59138cf7607c9330fd5900f4ae0 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 13:55:44 -0800 Subject: [PATCH 3/5] docs(api): DEC-9's decider time; FR3 says core still exposes the core contracts --- docs/architecture/public-component-api.md | 2 +- docs/specs/AST-082-native-first-surfaces/spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 1a657dbaefd96..3308812fe67c0 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -510,7 +510,7 @@ role that an existing input already names. ### DEC-9 — Public-API review searches for the same role and raises every mismatch **Reference:** `architecture:public-component-api/DEC-9` -**Decider:** `cixzhang`, `2026-11-18 13:34 PT` +**Decider:** `cixzhang`, `2026-11-18 13:35 PT` The owner said: "when we have codebunny review API updates, we should hold a high bar for API consistency, it should search for related components and diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index 6b5c2ba10eb71..b12eae63309c5 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -108,7 +108,7 @@ depends only on runtimes it can maintain. web caller's types, because the web types are the core contract plus the web contract; native contracts stop offering it. - Every public prop is defined in the private contracts package, which each - package builds in. Astryx manages each prop there for every surface at + package builds in; `@astryxdesign/core` still exposes the core contracts (FR5). Astryx manages each prop there for every surface at once. A new prop is a permanent part of every contract that carries it, so admitting one is a high bar (`spec:AST-002/DEC-1`): when a better default behavior meets the need, the component changes its default and adds no From 6287bef2cdf17c626bae2c0a1d40feb79d8db53d Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 14:23:11 -0800 Subject: [PATCH 4/5] docs(api): a bare ref conforms; Popover anchorRef is a shipped gap; Lab conforms on promotion; the contracts-package bullet and DEC-17 move to their own record change --- docs/architecture/public-component-api.md | 16 ++++++++++------ .../AST-082-native-first-surfaces/spec.md | 19 ------------------- 2 files changed, 10 insertions(+), 25 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 3308812fe67c0..b5367691f5eca 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -338,7 +338,9 @@ guidance owns the process used to propose and test APIs. returns for the caller to attach also ends in `Ref` and has the type `RefCallback` or `RefObject`, as `usePopover`'s `triggerRef` and `useHoverCard`'s `positionRef` do. A name that ends in `Ref` holds a ref - and nothing else. A function that computes an element from its arguments, + and nothing else. A bare `ref` conforms: a component's `ref` prop (INV8), + and a hook's element ref, as an option or a return, when the element has no + narrower job (INV2). A function that computes an element from its arguments, such as `useGridFocus`'s `getFocusTarget(cell)`, is a callback, not an element input. A prop that names the same role as an existing prop uses that prop's name and wording: the element a layer sits on is `anchorRef`, @@ -362,7 +364,7 @@ guidance owns the process used to propose and test APIs. the existing member that the row must match, and does not mark a mismatch as optional. A row that matches no existing role states that it found none. A new prop that the component can replace with a better default - behavior is a finding (INV4, `spec:AST-082` FR3). + behavior is a finding (INV4). This record applies to stable public packages, and INV23 also applies to Lab source. Lab components are not stable public promises until promotion. @@ -500,7 +502,7 @@ of react", and, on `usePopover`'s anchor: "so it should be anchorRef to match, I think we have patterns like this in hovercard/tooltip? Match the language". A `Ref` suffix tells a caller the input wants a ref before they read its type. One name per role lets a caller who knows Tooltip's -`anchorRef` find Popover's and `usePopover`'s. A ref is React-only, so the +`anchorRef` find Popover's. A ref is React-only, so the core contract states the need without one (`spec:AST-082` FR4). Rejected: an input that takes a ref or a getter, because the name cannot say @@ -545,7 +547,7 @@ Rejected: reviewing a new name only against its own component. | INV23 | `@astryx/no-raw-private-attribute` lint with its baseline (test files exempt), plus public-API review of the public list | A `data-astryx-*` name or selector written outside its owner module, a test, or the public list; a `dataAttr()` call that names a private attribute; an owner module that exports its raw name or a selector; a package that imports another package's owner module; a caller that sets a property an owner style it spreads also sets; a private attribute in a public export, `.doc.mjs`, or Changeset; a baseline entry added; a public data attribute changed without INV9 evidence | | INV24 | Generator tests, CI's merge-base-to-head surface compare, and the review bot's per-PR API delta | A promised export, prop, hook, type, custom property, theme target, public attribute, or event is missing from the delta; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; the merge gate passes a pull request that changes a published package when the compare artifact is missing or the generator errors; the review bot's summary notes do not start with the delta or "New public API: none"; a delta row decides acceptance | | INV25 | Public-API review routing against the pull request's API delta | A row that no current record decides does not reach human review; a row a current record decides is held for a human; an undeclared row alone draws a request for changes | -| INV29 | Public-API review of the generated declaration inventory (INV24); a lint rule is a known gap | A public prop, hook option, or returned ref that holds a React ref and does not end in `Ref`; a `…Ref` member whose type is not a ref; a ref input that also accepts a bare element or a getter; a new input for a role that an existing input already names, under a different name or wording | +| INV29 | Public-API review of the generated declaration inventory (INV24); a lint rule is a known gap | A public prop, hook option, or returned ref that holds a React ref and does not end in `Ref`, other than a bare `ref` that INV8 or INV2 allows; a `…Ref` member whose type is not a ref; a ref input that also accepts a bare element or a getter; a new input for a role that an existing input already names, under a different name or wording | | INV30 | The review bot's API delta notes and its findings on the pull request | A delta row with no search for existing members of the same role; a mismatch with an existing member, INV2, INV29, DEC-1, or the API conventions that review does not raise; a mismatch marked optional | | Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices | @@ -595,8 +597,10 @@ Known verification gaps: - INV29 gap: no lint rule checks the `Ref` suffix or the ref type; public-API review is the only check. Three shipped inputs break the rule: `useMenuPress`'s `getScroller` and `useLayerDismissal`'s `getContainer` take - a getter, and Lab ChatVirtualizer's `scrollElement` takes an element. - INV21a keeps the two shipped hook options until a real need arises. + a getter, and Popover's `anchorRef` takes `RefObject`, which + excludes `null`. INV21a keeps them until a real need arises. Lab + ChatVirtualizer's `scrollElement` takes an element; it must conform on + promotion, since this record applies to stable public packages. - The passthrough lint is warning-only while known violations remain. - The current source-to-doc completeness matcher still looks for old prefixed props interfaces, so it does not yet prove full prop coverage. diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index b12eae63309c5..6f5895991f044 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -107,12 +107,6 @@ depends only on runtimes it can maintain. prop. Moving a released prop from the core to the web contract changes no web caller's types, because the web types are the core contract plus the web contract; native contracts stop offering it. - - Every public prop is defined in the private contracts package, which each - package builds in; `@astryxdesign/core` still exposes the core contracts (FR5). Astryx manages each prop there for every surface at - once. A new prop is a permanent part of every contract that carries it, so - admitting one is a high bar (`spec:AST-002/DEC-1`): when a better default - behavior meets the need, the component changes its default and adds no - prop. - The web contract holds the web base props: styling inputs, DOM events, refs, element choice, and HTML attributes. - A component may exist on some platforms only; using it elsewhere fails at @@ -716,19 +710,6 @@ it once as durable intent rather than repeating it in each platform's entry. Rejected: iOS platform-entry terms only, because every other native platform would need the same words again. -### DEC-17 — Props live in the contracts package, and a new prop is a high bar - -**Reference:** `spec:AST-082/DEC-17` -**Decider:** `cixzhang`, `2026-11-18 13:35 PT` - -The owner said: "we should be wary of adding new props in general since they -become permanent additions to our contract. Once we put contract into a -separate lib, we should move all props there and they will be centrally -managed and considered across all surfaces". One home for every prop lets a -new prop be judged against every surface before it ships. - -Rejected: props defined in each package and reconciled later. - ## Open questions - **OQ1 — What thresholds make a candidate supported?** (`human-design`) From 5bc8a112dce10d4d3be28be82b9d390cea3ed192 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 14:56:37 -0800 Subject: [PATCH 5/5] docs(api): INV29 allows a combined returned ref; useLayer's returned trigger ref is a shipped gap; the same-role rule covers hook options --- docs/architecture/public-component-api.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index b5367691f5eca..dfe52c52e89be 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -338,12 +338,15 @@ guidance owns the process used to propose and test APIs. returns for the caller to attach also ends in `Ref` and has the type `RefCallback` or `RefObject`, as `usePopover`'s `triggerRef` and `useHoverCard`'s `positionRef` do. A name that ends in `Ref` holds a ref - and nothing else. A bare `ref` conforms: a component's `ref` prop (INV8), - and a hook's element ref, as an option or a return, when the element has no - narrower job (INV2). A function that computes an element from its arguments, + and nothing else. A bare `ref` conforms: a component's `ref` prop (INV8); a + hook's element ref, as an option or a return, when the element has no + narrower job (INV2); and a returned ref that combines several refs for one + element, as `useTooltip`'s and `useHoverCard`'s `ref` do. A function that + computes an element from its arguments, such as `useGridFocus`'s `getFocusTarget(cell)`, is a callback, not an - element input. A prop that names the same role as an existing prop uses - that prop's name and wording: the element a layer sits on is `anchorRef`, + element input. A prop or hook option that names the same role as an + existing one uses its name and wording: the element a layer sits on is + `anchorRef`, as on Tooltip, Popover, and BaseTypeahead; the element that opens a layer is `triggerRef`, as on `useMenuPress` and `useTouchTrigger`; and an imperative handle is `handleRef`, as on Calendar, Carousel, and @@ -547,7 +550,7 @@ Rejected: reviewing a new name only against its own component. | INV23 | `@astryx/no-raw-private-attribute` lint with its baseline (test files exempt), plus public-API review of the public list | A `data-astryx-*` name or selector written outside its owner module, a test, or the public list; a `dataAttr()` call that names a private attribute; an owner module that exports its raw name or a selector; a package that imports another package's owner module; a caller that sets a property an owner style it spreads also sets; a private attribute in a public export, `.doc.mjs`, or Changeset; a baseline entry added; a public data attribute changed without INV9 evidence | | INV24 | Generator tests, CI's merge-base-to-head surface compare, and the review bot's per-PR API delta | A promised export, prop, hook, type, custom property, theme target, public attribute, or event is missing from the delta; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; the merge gate passes a pull request that changes a published package when the compare artifact is missing or the generator errors; the review bot's summary notes do not start with the delta or "New public API: none"; a delta row decides acceptance | | INV25 | Public-API review routing against the pull request's API delta | A row that no current record decides does not reach human review; a row a current record decides is held for a human; an undeclared row alone draws a request for changes | -| INV29 | Public-API review of the generated declaration inventory (INV24); a lint rule is a known gap | A public prop, hook option, or returned ref that holds a React ref and does not end in `Ref`, other than a bare `ref` that INV8 or INV2 allows; a `…Ref` member whose type is not a ref; a ref input that also accepts a bare element or a getter; a new input for a role that an existing input already names, under a different name or wording | +| INV29 | Public-API review of the generated declaration inventory (INV24); a lint rule is a known gap | A public prop, hook option, or returned ref that holds a React ref and does not end in `Ref`, other than a bare `ref` that INV29 allows; a `…Ref` member whose type is not a ref; a ref input that also accepts a bare element or a getter; a new input for a role that an existing input already names, under a different name or wording | | INV30 | The review bot's API delta notes and its findings on the pull request | A delta row with no search for existing members of the same role; a mismatch with an existing member, INV2, INV29, DEC-1, or the API conventions that review does not raise; a mismatch marked optional | | Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices | @@ -595,10 +598,11 @@ Known verification gaps: by adding its factory; a shipped hook's signature changes only when a real need arises (INV21a). - INV29 gap: no lint rule checks the `Ref` suffix or the ref type; - public-API review is the only check. Three shipped inputs break the rule: + public-API review is the only check. Four shipped members break the rule: `useMenuPress`'s `getScroller` and `useLayerDismissal`'s `getContainer` take - a getter, and Popover's `anchorRef` takes `RefObject`, which - excludes `null`. INV21a keeps them until a real need arises. Lab + a getter, Popover's `anchorRef` takes `RefObject`, which + excludes `null`, and `useLayer` returns its trigger ref as `ref`, not + `triggerRef`. INV21a keeps them until a real need arises. Lab ChatVirtualizer's `scrollElement` takes an element; it must conform on promotion, since this record applies to stable public packages. - The passthrough lint is warning-only while known violations remain.