Skip to content

feat(charts): streamGL's handleRef accepts a callback ref - #12559

Draft
marie-lucas wants to merge 4 commits into
mainfrom
charts/streamgl-handle-ref
Draft

marie-lucas wants to merge 4 commits into
mainfrom
charts/streamgl-handle-ref

Conversation

@marie-lucas

@marie-lucas marie-lucas commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

User need

A builder who streams data into streamGL() needs to know when its push/clear handle exists, for example to seed initial points or replay buffered samples. Chart mounts its series only after it measures its width. So a caller's mount effect runs before the handle attaches, and handleRef.current is still null at that point. Today handleRef takes only a mutable object ref. The only way to observe the attach is to hand-write an object with a current getter/setter, which is easy to get wrong and differs from every other Astryx handle. React already has a standard answer for this: a callback ref. The type rejects it.

Problem and solution fit

  • Primary: StreamGLOptions.handleRef is widened from MutableRefObject<StreamGLHandle | null> to Ref<StreamGLHandle>. A callback ref then type-checks, and React calls it with the handle when it attaches and with null when it detaches. The runtime already passes the ref to useImperativeHandle, which accepts callback refs, so the internal cast is removed and no runtime code changes.
  • Supporting: architecture:public-component-api INV8 states the rule that decides this API. Core and Lab handles already follow it, and so does streamGL from this PR on.
  • Supporting: the JSDoc example shows both ref forms, and focused tests cover both.

Current specification

architecture:public-component-api owns public ref admission and naming, handleRef included, as architecture:react-component-runtime ("DOM and imperative API boundary") states. This PR amends PCA INV8 (Refs follow React 19):

In every package, a public ref through which a component or a definition exposes an imperative handle takes Ref<Handle>, so it accepts an object ref or a callback ref (DEC-7). React calls a callback ref with the handle when the handle attaches, so the caller learns when the handle is ready. When the handle detaches, a cleanup the callback ref returned runs; a callback ref without a cleanup is called with null. A chart series definition's handleRef, such as streamGL's, is one application.

The DOM-ref sentence of INV8 is unchanged and keeps its scope. The PR also:

  • adds DEC-7 — Every package's handle refs accept callback refs (Decider cixzhang, 2026-11-19 17:20 PT): callback refs for imperative handles are a convention of the whole system, not of one package. Rejected: accepting callback refs only in the packages that ask for them;
  • adds packages/charts/src/ and packages/vega/src/ to applies_to, and says in the record's scope lines that the handle-ref rule applies in every package, Lab, Charts and Vega included;
  • adds "a handleRef that exposes a handle rejects a callback ref" to the INV1/INV8 failure signal and lists packages/charts/src/marks/marks.test.tsx under verified_by.

Every exported handleRef that exposes a handle in Core and Lab already uses Ref<Handle>. streamGL was the only exception, and it conforms in this PR, so the record has no gap line.

The record change needs the spec owner's /approve-spec at the exact head.

Public delta and caller burden

Before After
StreamGLOptions.handleRef MutableRefObject<StreamGLHandle | null> Ref<StreamGLHandle> (object ref or callback ref)

Before:

const streamRef = useRef<StreamGLHandle>(null);
<Chart series={[streamGL({color: '#10b981', handleRef: streamRef})]} />
// To seed data on attach, a caller had to build a getter/setter object.

After (both work):

const streamRef = useRef<StreamGLHandle>(null);
<Chart series={[streamGL({color: '#10b981', handleRef: streamRef})]} />

const handleRef = useRef<StreamGLHandle | null>(null);
const samples = useRef([{x: 0, y: 50}]);
const attach = useCallback((handle: StreamGLHandle | null) => {
  handleRef.current = handle;
  if (handle == null) return;
  // The buffer may be new or kept, so replay it.
  handle.clear();
  for (const s of samples.current) handle.push(s.x, s.y);
}, []);
// Keep at most bufferSize (500 by default) samples, so a replay stays bounded.
const pushPoint = (point: {x: number; y: number}) => {
  samples.current = [...samples.current, point].slice(-500);
  handleRef.current?.push(point.x, point.y);
};
<Chart series={[streamGL({color: '#10b981', handleRef: attach})]} />
  • Compatibility: this is a widening only. Every existing object ref still type-checks, because MutableRefObject<StreamGLHandle | null> is assignable to Ref<StreamGLHandle>, and it still behaves the same. No default, behavior, theming or accessibility change.
  • New caller decision: only for callers who choose a callback ref. Keep it stable, for example with useCallback, because React calls a new function again on each render, as with any callback ref. React calls it on every attach, and the stream buffer can be new or kept, so replay the samples to show: clear, then push. For example, an Activity that shows the chart again keeps the buffer, while a chart at width 0, such as in a hidden tab panel, unmounts the series and discards it. The JSDoc example shows the pattern.
  • @astryxdesign/charts is canary-only, so this PR has no Changeset.

Design and alternatives

The handle stays a standard React ref, as on every other Astryx handleRef. Rejected: an onReady callback option, because it would be a second API for the job a callback ref already does (PCA INV21).

Evidence

Tests in packages/charts/src/marks/marks.test.tsx:

  1. Compile time: expectTypeOf(streamGL).toBeCallableWith(...) accepts createRef<StreamGLHandle>() and a callback ref.
  2. Runtime: a callback ref is called once with {push, clear} after the series mounts. The handle works, and unmount calls the ref with null.

Red arms:

  • Previous streamGL.tsx restored with the new tests kept: tsc fails with TS2322: Type 'Mock<(handle: StreamGLHandle | null) => void>' is not assignable to type 'MutableRefObject<StreamGLHandle | null> | undefined' at the two callback-ref lines.
  • The runtime test passes on the previous code too, because the runtime already handled callback refs; the type is what this PR changes. Two mutations show the test is sensitive:
    • The handle goes only to an object ref: expected "vi.fn()" to be called 1 times, but got 0 times.
    • Detach never passes null: expected "vi.fn()" to be called 2 times, but got 1 times.

Green:

  • marks.test.tsx: 27/27.
  • Charts suite: 12 files, 126/126.

Unchanged legacy paths:

  • The existing object-ref test in marks.test.tsx passes, and so do the object-ref cases in glEffectReplay.test.tsx (StrictMode replay, Activity hide and show).
  • The Charts/WebGL Streaming story is unchanged and still type-checks with its object ref.

Scope

Components: streamGL (charts mark)

  • One capability is added.
  • Unrelated fixes, cleanup, and policy changes were removed or split.
  • Consumer docs, focused tests, and migration evidence ship with the feature.
  • Public text and artifacts contain no internal Meta context.

Testing

  • pnpm check:knowledge: records aligned
  • pnpm exec prettier --check and pnpm exec eslint --max-warnings=0 on the changed files
  • pnpm -F @astryxdesign/charts typecheck (after building core and charts)
  • pnpm exec vitest run packages/charts
  • pnpm specs:for --diff origin/main: no concern-routed claims for the added lines
  • pnpm review:pre: 0 findings
  • pnpm check:changesets and pnpm check:repo

No visual change, so real-browser captures don't apply.

Writing rubric results

  • R1 narration: none. The new INV8 sentences are present tense and describe the system.
  • R2 research in the record: none. The conformance check of existing handles is in this description, not the record.
  • R3 evidence naming a change: none. The verification cell names a failure signal, and verified_by names a test file.
  • R4 rejected alternatives over one line or outside a decision: none added to the record.
  • R5 pull request or issue references remaining: none in the delta (searched for # plus digits, /pull/, /issues/).
  • R6 ruled open questions still listing options: none added.
  • R7 project status (build status or work order): none. The rule and its only nonconforming site change together, so the record has no gap line.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Building Building Preview Nov 20, 2026 2:54am UTC

Request Review

@astracat-bot

astracat-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 20, 2026, 2:54 AM UTC

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 18, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL type change rests on, and two fixes are needed either way.

An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request (the author may, as an engineering owner), and the decision includes whether this record, written for stable components, covers chart series definitions in the canary charts package.

Blocking findings:

  • The new seed example in streamGL.tsx (lines 355-361) pushes (0, 50) again each time the handle re-attaches, for example when an <Activity> shows the chart again or under StrictMode, so the chart draws a line from the newest sample back to the seed point; document that the callback runs on every attach and seed once behind a ref.
  • The new INV1/INV8 failure signal "a handleRef rejects a callback ref" (public-component-api.md line 468) also fires on SideNavCollapseButton's public handleRef, which takes SideNav's handle as input; scope it to "a handleRef that exposes a handle rejects a callback ref".

CI did not run on this head because the CI queue was full, so it needs a re-run.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: handleRef widens to Ref<StreamGLHandle>. Verified at streamGL.tsx:51 and :98.
  • Claim: the internal cast is removed and runtime behavior is unchanged. Verified: streamGL.tsx:277, and the new runtime test also passes against the previous streamGL.tsx.
  • Claim: Chart mounts its series only after it measures its width. Verified at Chart.tsx:359.
  • Claim: a callback ref gets the handle after mount and null on unmount. Verified by marks.test.tsx:454-475. It is also called again on every re-attach (finding above).
  • Claim: every exported handleRef in Core and Lab that exposes a handle already takes Ref<Handle>. Verified for those props. SideNavCollapseButton's handleRef takes a handle as input and is typed RefObject (finding above).
  • Claim: existing object refs still type-check and behave the same. Verified by the compile-time test and the object-ref cases in glEffectReplay.test.tsx.
  • Claim: the canary-only charts package needs no Changeset. Verified: the package is private and canary-only, and the Changeset check refuses private packages.
  • Claim: with the previous streamGL.tsx, the new tests fail type-checking with TS2322 at the two callback-ref lines. Verified at marks.test.tsx:450 and :457.
  • Claim: marks.test.tsx passes 27/27 and the charts suite passes 126/126. Verified on this head.
  • Claim: the charts typecheck passes after Core and Charts are built. Verified on this head.
  • Claim: the WebGL streaming story still type-checks with its object ref. Verified by reading: it passes a MutableRefObject, which Ref<StreamGLHandle> accepts.
  • Claim: there is no visual change. Verified: the change is type, docs and tests only.
  • Claim: the record text has no narration, status lines or references. Verified.
  • File docs/architecture/public-component-api.md: failure-signal finding; the INV8 amendment awaits an owner decision.
  • File packages/charts/src/marks/streamGL.tsx: seed-example finding.
  • File packages/charts/src/marks/marks.test.tsx: clear.

Automated review (maintainer link)

Comment thread packages/charts/src/marks/streamGL.tsx Resolved

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL handleRef type change rests on; no blocking defect remains, and both earlier findings are fixed.

An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request (the author may, as an engineering owner), and the decision includes whether this record, written for stable components, covers chart series definitions in the canary charts package. The CI workflow did not run its typecheck, tests or build on this head because CI was full, so it needs a re-run.

Optional suggestions:

  • Miss: React 19 runs the cleanup a callback ref returns instead of calling it with null, so INV8's new sentence and the handleRef JSDoc could end with "unless it returned a cleanup function, which React runs instead".
  • The JSDoc example's samples list is never trimmed, so a per-frame stream keeps every point and replays all of them on each attach; keeping only the last bufferSize samples avoids that.
Claims and files checked

Review mode: full; reason: history

  • Claim: handleRef widens to Ref<StreamGLHandle>. Verified at streamGL.tsx:52 and :99.
  • Claim: the internal cast is removed and no runtime code changes. Verified at streamGL.tsx:277-278; the new runtime test also passes against the previous streamGL.tsx.
  • Claim: Chart mounts its series only after it measures its width. Verified at Chart.tsx:359.
  • Claim: a callback ref gets the handle when it attaches and null when it detaches. Verified by marks.test.tsx:454-475; a callback that returns a cleanup gets the cleanup instead (suggestion above).
  • Claim: every exported Core and Lab handleRef that exposes a handle already takes Ref<Handle>, so the record needs no gap line. Verified; SideNavCollapseButton's takes a handle as input and the date scroller's is not exported.
  • Claim: existing object refs still type-check and behave the same. Verified by the charts typecheck and the object-ref StrictMode and Activity tests.
  • Claim: an Activity that shows the chart again keeps the buffer, and a chart at width 0 unmounts the series and discards it. Verified by reading streamGL.tsx:115-120, :311-336 and Chart.tsx:359.
  • Claim: the documented callback-ref pattern replays correctly on every attach. Verified on the head: each point is drawn once after StrictMode replay and after an Activity hide and show.
  • Claim: the canary-only charts package needs no Changeset. Verified: packages/charts/package.json is private and canary-only.
  • Claim: with the previous streamGL.tsx, the new tests fail type-checking with TS2322 at the two callback-ref lines. Verified at marks.test.tsx:450 and :457.
  • Claim: the runtime test passes on the previous code too, and the two mutations would fail it. Verified 27/27 on the previous code; the mutation results follow from the assertions at marks.test.tsx:462 and :473-474.
  • Claim: marks.test.tsx passes 27/27 and the charts suite 12 files, 126/126. Verified on the head.
  • Claim: the charts typecheck passes after building Core and Charts. Verified on the head.
  • Claim: the Streaming story is unchanged and still type-checks with its object ref. Verified by reading: it passes a MutableRefObject, which Ref<StreamGLHandle> accepts.
  • Claim: knowledge, formatting and lint checks pass. Verified for the knowledge check, Prettier and ESLint on the changed files; the Lint workflow also passed.
  • Claim: there is no visual change. Verified: type, docs and tests only.
  • Claim: the record delta has no narration, research, status, or pull request references. Verified.
  • File docs/architecture/public-component-api.md: the INV8 amendment awaits an owner decision; optional cleanup wording.
  • File packages/charts/src/marks/streamGL.tsx: clear apart from two optional wording suggestions.
  • File packages/charts/src/marks/marks.test.tsx: clear.

Automated review (maintainer link)

Comment thread packages/charts/src/marks/streamGL.tsx Resolved
Comment thread packages/charts/src/marks/streamGL.tsx Resolved
architecture:public-component-api INV8 states that a public handleRef,
on a component or a chart series definition, takes Ref<Handle>, so it
accepts an object ref or a callback ref. React calls a callback ref
with the handle when it attaches. On detach, React runs the cleanup it
returned, or calls it with null.

streamGL's handleRef now takes Ref<StreamGLHandle>. A caller can learn
when the handle is ready, for example to seed data once the chart
mounts the series. Object refs work as before. The internal cast is
gone, and the JSDoc example shows both ref forms.

Tests cover both ref forms at compile time and the callback ref's
attach and detach at runtime. The record lists the test file under
verified_by.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL handleRef type change rests on; no defect remains at this head.

  • Owner decision: an engineering owner approves the amended INV8 sentences and the scoped INV1/INV8 failure signal by commenting /approve-spec <full head SHA> on this pull request, or says what INV8 should state instead; the author is an engineering owner and may do so, and approving also brings chart series definitions in the canary charts package under INV8.

The earlier notes are fixed: INV8 and the option JSDoc now describe React's cleanup-or-null detach, and the example keeps at most 500 samples. CI's typecheck, test and build legs were cancelled because CI was full, so they need a re-run at this head.

Claims and files checked

Review mode: full; reason: history

Claims:

  • Chart mounts its series only after it measures its width, so a caller's mount effect sees a null handle: verified (Chart.tsx:172, :359).
  • Before this change handleRef took only a mutable object ref: verified (base streamGL.tsx).
  • The type widens to Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52, :99, :277-278).
  • The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
  • Every exported Core and Lab handleRef that exposes a handle already takes Ref<Handle>: verified (inventory of handleRef declarations).
  • Existing object refs still type-check and behave the same: verified (charts typecheck with the object-ref test; the Streaming story passes a useRef<StreamGLHandle | null>).
  • A callback ref should be stable because React calls a new function again: verified (React re-runs the imperative handle when the ref changes).
  • The buffer is kept across an Activity show and discarded at width 0: verified (Chart.tsx:359; probe replays into a new buffer after width 0).
  • No changeset because the charts package is canary-only: verified (private package; the changeset check refuses a private package).
  • Tests cover both ref forms at compile time and the callback ref at runtime: verified (marks.test.tsx:441-475, 27/27).
  • With the previous streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322 at :450 and :457).
  • The runtime test also passes on the previous code, and the two described mutations would fail it: verified (27/27 with the base runtime; the call-count and null assertions).
  • The charts suite passes 126/126, including the object-ref replay cases: verified.
  • Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the full repository check, the pre-review checklist and the diff-routed spec lookup were not rerun.
  • The amended INV8 matches React's detach behavior and the bottom-sheet switcher's FR9: verified (probe: handle then cleanup; handle and null without a cleanup).
  • The record delta meets the writing rubric (present tense, no references or project status): verified.
  • No visual change: verified.

Files:

  • docs/architecture/public-component-api.md: text accurate; approval waits on an engineering owner's decision on the INV8 amendment.
  • packages/charts/src/marks/streamGL.tsx: clear.
  • packages/charts/src/marks/marks.test.tsx: clear.

Automated review (maintainer link)

@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec d2d63ff

@cixzhang

Copy link
Copy Markdown
Contributor

/revoke-spec d2d63ff

@cixzhang
cixzhang marked this pull request as draft November 20, 2026 01:25
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 0dab8f2

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the streamGL handleRef widening and the owner-approved callback-ref rule are sound, but the record's new every-package INV8 scope leaves gaps it does not name, and the description no longer matches the record.

  • INV8 now says every package's public DOM components accept ref (docs/architecture/public-component-api.md:157-159), but Charts' ChartAxis, ChartGrid, ChartLegend, ChartSwatch and ChartTooltip and Lab components such as ChatReasoning and TabBarMoreList take no ref and the record names no INV8 gap: line, so either put "In every package" on the handle-ref sentence only, which is what DEC-7 decides, or add that gap line.
  • The record still says it covers stable packages only (:73, and :344: "applies to stable public packages, and INV23 also applies to Lab source"), which contradicts INV8's every-package scope and the new Charts and Vega applies_to entries, so amend :344 and :73 to say where INV8 applies.
  • The description's "Current specification" quotes an INV8 sentence this head no longer has and leaves out DEC-7 and the applies_to additions, so update it to match the record at this head.

Everything else checks out: the type change is compatible, the new tests fail against the base and pass here, and the earlier notes are fixed. The record edits will need a fresh /approve-spec from an engineering owner at the new head, and CI has not run on this draft yet.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • Chart mounts its series only after it measures its width, so a caller's mount effect sees no handle yet: verified (Chart.tsx:172, :359).
  • Before this change handleRef took only a mutable object ref: verified (base streamGL.tsx).
  • The type widens to Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52, :99, :277-278).
  • The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
  • The pull request amends INV8 to the quoted handleRef sentence: false (INV8 at public-component-api.md:157-165 now reads differently, and DEC-7 and the Charts and Vega applies_to entries are not mentioned).
  • The failure signal is added and the charts test is listed under verified_by: verified (:484, :30).
  • Every exported Core and Lab handleRef that exposes a handle already takes Ref<Handle>: verified (inventory of handleRef declarations).
  • streamGL was the only nonconforming site, so the record needs no gap line: false (INV8's every-package DOM-ref sentence is unmet by ChartLegend.tsx:31, ChartSwatch.tsx:27 and others).
  • Existing object refs still type-check and behave the same: verified (charts typecheck; object-ref tests pass; the Streaming story passes a useRef<StreamGLHandle | null>).
  • A callback ref should be stable because React calls a new function again: verified (React adds the ref to the handle's dependencies).
  • The buffer is kept when the same series re-attaches and discarded when the chart's width drops to 0: verified (per-instance ring ref at streamGL.tsx:115; Chart.tsx:359 unmounts the series).
  • No changeset because the charts package is canary-only: verified (private package; the changeset check passes).
  • Tests cover both ref forms at compile time and the callback ref at runtime: verified (marks.test.tsx:441-475).
  • With the previous streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322 at marks.test.tsx:450 and :457).
  • The runtime test also passes on the previous code, and the call-count and null assertions catch the two described mutations: verified (27/27 on the base runtime; :462, :473-474).
  • marks.test.tsx passes 27/27 and the charts suite 126/126, object-ref replay cases included: verified.
  • Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the diff-routed spec lookup, the pre-review checklist and the repository check were not rerun.
  • No visual change: verified.
  • The record delta meets the writing rubric: R1 and R5 verified; R7's claim that the rule's only nonconforming site changes with it is false (see above).

Files:

  • docs/architecture/public-component-api.md: two findings (INV8 gap for Charts and Lab DOM components; stable-only scope at :73 and :344).
  • packages/charts/src/marks/streamGL.tsx: clear.
  • packages/charts/src/marks/marks.test.tsx: clear.

Automated review (maintainer link)

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 232e338

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet. The pull request is a draft, so CI skipped every job; it runs once the pull request is marked ready for review.

The streamGL handleRef widening is compatible, the new type test fails against the previous streamGL.tsx and passes here, and the runtime test shows the callback ref receives the handle on attach and null on unmount. The owner-approved record change now applies "every package" to handle refs only, the scope lines say so, and the description matches the record, so the three earlier findings are fixed.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • Chart mounts its series only after it measures its width, so a caller's mount effect sees no handle yet: verified (Chart.tsx:172, :359).
  • Before this change handleRef took only a mutable object ref: verified (base streamGL.tsx).
  • The type widens to Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52, :99, :277-278).
  • The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
  • The pull request amends INV8 with the quoted handle-ref sentences: verified (public-component-api.md:159-166).
  • INV8's DOM ref sentence is unchanged and keeps its scope: verified (:158-159, :345).
  • DEC-7 is added with its decider and rejected alternative: verified (:472-481).
  • Charts and Vega join applies_to, and the scope lines say the handle-ref rule applies in every package: verified (:19-20, :74, :345-347).
  • The failure signal is added and the charts test is listed under verified_by: verified (:487, :30).
  • Every exported Core and Lab handleRef that exposes a handle already takes Ref<Handle>, and streamGL was the only exception, so the record needs no gap line: verified (handle inventory; the one RefObject handle, MonthScroller, is not exported).
  • The record change needs an engineering owner's approval at this head: verified (present).
  • Existing object refs still type-check and behave the same: verified (charts typecheck; object-ref tests pass; the Streaming story has no type error).
  • A callback ref should be stable, React calls it on every attach, and the buffer may be new or kept: verified (React adds the ref to the handle's dependencies; per-instance ring at streamGL.tsx:115; Chart.tsx:359 unmounts the series at width 0).
  • No changeset because the charts package is canary-only: verified (private package; the changeset check passes).
  • An onReady option was rejected as a second API for the same job: consistent with INV21.
  • Tests cover both ref forms at compile time and the callback ref at runtime: verified (marks.test.tsx:441-475).
  • With the previous streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322 at marks.test.tsx:450 and :457).
  • The runtime test also passes on the previous code, and its call-count and null assertions catch the two described mutations: verified (runtime code unchanged; :462, :473-474).
  • marks.test.tsx passes 27/27 and the charts suite 126/126, object-ref replay cases included: verified.
  • Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the diff-routed spec lookup, the pre-review checklist and the repository check were not rerun.
  • No visual change: verified.
  • The record delta meets the writing rubric (present tense, no pull request references, no status or gap line needed): verified.

Files:

  • docs/architecture/public-component-api.md: clear.
  • packages/charts/src/marks/streamGL.tsx: clear.
  • packages/charts/src/marks/marks.test.tsx: clear.

Automated review (maintainer link)

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 8f4c3a5

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026

This branch was successfully deployed

1 active (outdated) deployment
Preview — 232e3382 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants