proposal: downstream binding preview flow for unreleased blend-design-system changes

[jagguji]

Context

juspay/blend-design-system publishes a pkg.pr.new preview for every PR / push to dev (via their ci.yml preview job). A ReScript consumer can grab that preview by installing:

npm install https://pkg.pr.new/@juspay/blend-design-system@<sha>

Today's escape hatch: if the consumer writes their own bindings inline, they can use any new component / prop from that preview immediately. The bindings in @subham_/rescript-blend (this repo) are nice-to-have but not load-bearing.

The future we're moving toward: this package becomes the canonical source of ReScript bindings, and consumers stop writing local wrappers. The moment that happens, consuming an unreleased blend change requires a matching, unreleased binding — and we don't have a flow for that yet.

Problem

When a dev wants to test an unmerged blend PR from their ReScript app, they need two artefacts at matching versions:

1. The preview @juspay/blend-design-system@<blend-sha>
2. A preview of @juspay/rescript-blend where src/*.res has been regenerated against that blend SHA.

Without (2), any new component / prop in the blend preview is unreachable from ReScript — the app compiles against stale bindings that don't know the new API exists.

The existing sync-bindings.yml in this repo can generate the new bindings on workflow_dispatch, but it opens a PR and waits for human review and NPM release. That's fine for stable adoption (minutes → hours → days) but useless for "I want to try this blend PR right now."

Options

A. Manual generate + file: / yalc install

Dev clones blend-rescript, sets @juspay/blend-design-system to the pkg.pr.new URL in devDeps, runs npm run generate -- --all, then installs the resulting tree into their app via yalc or npm install file:../blend-rescript.

• 👍 Works today, no infra changes
• 👎 Every consumer repeats the toolchain setup (needs LITELLM_API_KEY etc.)
• 👎 Nothing in CI guarantees the generated bindings actually compile

B. workflow_dispatch → open PR → merge → wait for NPM release

The current sync-bindings.yml path. Review-gated, safe, but slow — not a fit for "I just want to try this PR."

C. Upstream dispatch → regenerate in CI → publish matching pkg.pr.new preview ⭐️

Add a step to blend-design-system's ci.yml that, after publishing its own preview, fires a repository_dispatch (blend-preview-published) into this repo with payload { blend_sha, blend_spec }.

This repo reacts:

1. Creates a branch preview/blend-<sha>.
2. npm install --no-save @juspay/blend-design-system@<blend_spec> — pins to that exact preview.
3. npm run generate -- --all — regenerate bindings.
4. rescript format -c + npm run build — gate on green.
5. Push the branch (does not open a PR — this is a preview, not a merge candidate).
6. pkg.pr.new GitHub App picks up the branch push and publishes https://pkg.pr.new/juspay/blend-rescript@<blend-rescript-sha>.

Dev then installs both URLs together:

npm install \
  https://pkg.pr.new/@juspay/blend-design-system@<blend-sha> \
  https://pkg.pr.new/juspay/blend-rescript@<blend-rescript-sha>

• 👍 Zero-friction for consumers — URLs appear automatically
• 👍 CI proves the bindings at least compile against that blend preview
• 👍 Previews expire with the branches, no garbage collection needed
• 👎 Requires re-installing the pkg.pr.new GitHub App on this repo (was dropped in ci: remove pkg.pr.new per-PR preview publishing #44)
• 👎 Requires a PAT on the blend side (BLEND_RESCRIPT_PAT, Actions: Write, Contents: Read on juspay/blend-rescript)
• 👎 Uses the LiteLLM quota for every blend PR — meaningful cost if blend ships many PRs

D. Don't solve it

Tell consumers: if you need an unreleased blend API, write a one-file inline binding locally. Accepts that the "canonical bindings" story has a permanent escape hatch for unreleased blend.

• 👍 Zero work
• 👎 Defeats the purpose of making this repo canonical

Recommendation

C, but with two guardrails:

• Preview-publish job runs only if the blend PR has a specific label (e.g. needs-rescript-preview). Default blend PRs skip it, which keeps LiteLLM cost bounded to the few PRs that actually need cross-language validation.
• Generated preview branches named preview/blend-<sha> are auto-deleted by a nightly workflow if older than 14 days, so the repo doesn't accumulate hundreds of dead branches.

What to decide before implementation

1. Re-install the pkg.pr.new GitHub App on this repo? (Was dropped in ci: remove pkg.pr.new per-PR preview publishing #44.)
2. Opt-in via label vs. every blend PR? (Cost vs. coverage.)
3. Who owns the BLEND_RESCRIPT_PAT secret on the blend side?
4. Is auto-publishing previews off .res regenerated by an LLM acceptable without human review? (Arguments both ways — compile success is a strong signal, but runtime correctness isn't checked.)

Out of scope here

• The in-repo bindings quality loop (already handled by sync-bindings.yml + 3-retry feedback).
• Stable release adoption (already handled by the manual sync-bindings.yml + PR review path).

[jagguji]

Good refinement. Splitting on "does the public TypeScript surface actually change?" means we only pay the LLM cost for the minority of blend PRs that touch it.

Two cases, two flows

Case 1 — blend PR doesn't change the public .d.ts surface

Examples: internal bug fix, perf improvement, refactor of a non-exported helper, test/doc-only change.

• Bindings in this repo are untouched. No preview of @subham_/rescript-blend is needed.
• Consumer installs:

  npm install https://pkg.pr.new/@juspay/blend-design-system@<blend-sha>
  

  plus whatever stable @subham_/rescript-blend@<current> they already have. The existing bindings still compile, because nothing they bind against has changed.

Case 2 — blend PR changes a .d.ts

Examples: new component, prop added/renamed, type changed, new variant in an enum, something re-exported.

• Bindings must be regenerated. Full option C flow from the issue body: branch preview/blend-<sha>, regenerate, build-gate, push, pkg.pr.new picks it up.
• Consumer installs both URLs together.

How we decide which case we're in — automatic, not a human label

The .d.ts files are the authoritative signal. Proposed workflow on this repo's dispatch handler:

# Install the currently-pinned blend (baseline)
CURRENT=$(node -p "require('./package.json').devDependencies['@juspay/blend-design-system']")
npm install --no-save "@juspay/blend-design-system@$CURRENT"
cp -r node_modules/@juspay/blend-design-system/dist/components /tmp/baseline

# Install the preview blend
npm install --no-save "@juspay/blend-design-system@$BLEND_SPEC"
cp -r node_modules/@juspay/blend-design-system/dist/components /tmp/preview

# Diff only the .d.ts files
if diff -r --brief --include='*.d.ts' /tmp/baseline /tmp/preview > /tmp/dts.diff; then
  echo "case=1" >> $GITHUB_OUTPUT   # no surface change
else
  echo "case=2" >> $GITHUB_OUTPUT
  cat /tmp/dts.diff                 # log what changed, for the PR comment
fi

Case 1 behaviour: workflow exits early, posts a comment on the blend PR: "No ReScript binding changes needed for this PR. Consume with the current published @subham_/rescript-blend." No branch created, no LLM call, no pkg.pr.new preview needed.

Case 2 behaviour: continue to the full regen + preview flow.

What this changes in the open decision list

Updating the four decision points from the issue body:

1. Re-install pkg.pr.new GitHub App? — only needed for Case 2. If Case 1 is ~80% of blend PRs (guess, worth measuring), the app is idle most of the time but cheap to keep installed.
2. Opt-in via label vs. every blend PR? — the .d.ts diff is the opt-in signal, and it's automatic and correct by construction. No human label needed. Fire dispatch on every blend PR, let the handler short-circuit when the surface is stable.
3. PAT ownership — unchanged, still needed on blend side.
4. Auto-publish LLM-regenerated bindings without human review? — narrower problem now. Case 1 never invokes the LLM so the risk vanishes for those. Case 2 still carries it; worth keeping "compile-green + preview-only, never auto-merged to main" as the guardrail.

Cost estimate under the two-case split

If we assume half-ish of blend PRs are internal-only (bug fixes, refactors, tests, CI) and half touch the public surface:

• Case 1: blend PR triggers a ~30-second CI job that installs two npm versions and runs diff. No LLM, no preview. Essentially free.
• Case 2: full regen. Minutes, and a chunk of LiteLLM quota per run.

vs. the unrefined proposal which paid Case 2 cost for every blend PR. Big win.

Ready to build?

If this refinement looks right, the implementation order is:

1. Write the dispatch handler on this repo (Case-1 short-circuit + Case-2 regen).
2. Re-add the pkg.pr.new workflow on this repo, gated to only run on preview/blend-* branches.
3. Add the dispatch-firing step on blend's ci.yml.
4. Provision BLEND_RESCRIPT_PAT on the blend side.

Step 1 is self-contained here. 2 is a tiny workflow file. 3 and 4 touch a repo we don't own, so they block on whoever maintains blend's CI.