@hyperframes/studio 0.7.95 → 0.7.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.95",
+  "version": "0.7.96",
   "description": "",
   "repository": {
     "type": "git",
@@ -47,11 +47,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.7.95",
-    "@hyperframes/core": "0.7.95",
-    "@hyperframes/player": "0.7.95",
-    "@hyperframes/sdk": "0.7.95",
-    "@hyperframes/studio-server": "0.7.95"
+    "@hyperframes/core": "0.7.96",
+    "@hyperframes/player": "0.7.96",
+    "@hyperframes/parsers": "0.7.96",
+    "@hyperframes/sdk": "0.7.96",
+    "@hyperframes/studio-server": "0.7.96"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -67,7 +67,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.95"
+    "@hyperframes/producer": "0.7.96"
   },
   "peerDependencies": {
     "react": "19",

package/src/telemetry/canary.test.ts

@@ -194,6 +194,8 @@ describe("telemetry", () => {
     expect(canaryEventProperties()).toEqual({
       "$feature/canary-on-everywhere": "true",
       "$feature/canary-off-everywhere": "false",
+      canary_reason_on_everywhere: "in_cohort",
+      canary_reason_off_everywhere: "out_of_cohort",
     });
 
     __resetStudioCanaryCacheForTests();
@@ -235,6 +237,8 @@ describe("telemetry opt-out is canary opt-out", () => {
     expect(canaryEventProperties()).toEqual({
       "$feature/canary-on-everywhere": "false",
       "$feature/canary-off-everywhere": "false",
+      canary_reason_on_everywhere: "telemetry_opt_out",
+      canary_reason_off_everywhere: "telemetry_opt_out",
     });
   });
 });
@@ -323,3 +327,24 @@ describe("CLI-launched Studio adopts the CLI's decisions", () => {
     });
   });
 });
+
+// A CLI-launched Studio shares the CLI's bucket seed, so a cohort flip can
+// surface on either surface. Attribution on only one of them makes the two
+// flip counts irreconcilable — which is why this is not a CLI-only property.
+describe("Studio attribution matches the CLI", () => {
+  it("distinguishes a local URL override from a cohort roll at the same value", () => {
+    setSearch("?hf_canary_off_everywhere=on");
+    const props = canaryEventProperties();
+    expect(props["$feature/canary-off-everywhere"]).toBe("true");
+    expect(props["canary_reason_off_everywhere"]).toBe("forced_on");
+    // Same assignment `on-everywhere` reaches by an ordinary roll.
+    expect(props["$feature/canary-on-everywhere"]).toBe("true");
+    expect(props["canary_reason_on_everywhere"]).toBe("in_cohort");
+  });
+
+  it("never puts a reason inside the $feature namespace", () => {
+    for (const [key, value] of Object.entries(canaryEventProperties())) {
+      if (key.startsWith("$feature/")) expect(value).toMatch(/^(true|false)$/);
+    }
+  });
+});

package/src/telemetry/canary.ts

@@ -257,12 +257,22 @@ export function isCanaryEnabled(name: string): boolean {
 }
 
 /**
- * Canary assignments as PostHog flag properties (`$feature/canary-<name>`),
- * attached to every Studio event so any metric can be split by cohort —
- * identical shape to the CLI, so a rollout spanning both reads as one flag.
+ * Canary assignments as PostHog flag properties (`$feature/canary-<name>`)
+ * plus their `canary_reason_<name>`, attached to every Studio event so any
+ * metric can be split by cohort — identical shape to the CLI, so a rollout
+ * spanning both reads as one flag.
+ *
+ * The reason has to be here too, not just CLI-side. A CLI-launched Studio
+ * adopts the CLI's decisions and shares its bucket seed, so a cohort flip can
+ * surface on either surface; emitting attribution on only one of them makes
+ * the two flip counts irreconcilable and leaves Studio-observed flips
+ * unattributable — the exact ambiguity this property exists to remove.
  */
 export function canaryEventProperties(): Record<string, string> {
   return canaryFeatureProperties(
-    CANARIES.map((c) => ({ name: c.name, enabled: resolveCanary(c.name).enabled })),
+    CANARIES.map((c) => {
+      const { enabled, reason } = resolveCanary(c.name);
+      return { name: c.name, enabled, reason };
+    }),
   );
 }