@precedence-dev/instrument 0.1.0 → 0.2.0

package/README.md

@@ -17,42 +17,67 @@ actually run the generated code to prove it.
 
 ```
 # dry-run: print the diff, touch nothing
-precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics"
+precedence-instrument --plan plan.json --dir src
 
 # apply it (refuses on a dirty git tree, so the injection lands in its own commit)
-precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics" --apply
+precedence-instrument --plan plan.json --dir src --apply
 
 # CI: fail the build if the committed source has drifted from the plan
-precedence-instrument --plan plan.json --dir src --track track --check
+precedence-instrument --plan plan.json --dir src --check
 ```
 
 `--plan` is the events export from the picker (`@precedence-dev/sdk`) or the viewer
 (`@precedence-dev/viewer`). `--dir` is repeatable. `-h` prints every flag.
 
-## Emit modes
+## What it bakes
 
-| `--emit` | injected call | change an event without a rebuild? |
-| --- | --- | --- |
-| `direct` (default) | `track("event_name", { pm_id, ...props })`, baked in; adds the `--track` import | no — it's all in the source |
-| `runtime` | `globalThis.__pm?.("<anchor id>", { ...in-scope props })`, no import | yes — enable/disable, rename, retarget, change the discriminator, narrow props: all plan edits |
+At every tracked branch it splices one complete call:
 
-`runtime` mode needs [`@precedence-dev/sdk`](https://github.com/precedence-dev/sdk)'s
-`installPrecedence` called once at your app root — it maps the anchor id back to
-the event name, adds `pm_id`, layers on the plan's static props, and catches the
-clicks on synthetic anchors (which `runtime` mode only stamps with `data-precedence-id`,
-no listener). In `direct` mode the delegated listener is generated instead —
-`--runtime <file>` writes it, import it once at the app root.
+```js
+precedence.track("checkout_completed", { psc_id: "p_1qzcbxk", amount });
+```
+
+plus `import { precedence } from "@precedence-dev/sdk"` in that file.
+
+- **`psc_id`** — a short cyrb53 hash of the anchor's structural id
+  (`src/Checkout.tsx#Checkout::form|onSubmit|ok`). The readable id never enters
+  the bundle or a third-party destination; the plan maps the two.
+- **the customer's selected properties** — `{ amount }` here, shorthand for an
+  in-scope binding, or an accessor expression, or `undefined /* not in scope */`.
+- **not** the `outcome` / `placement` discriminator — that stays in the plan and
+  the SDK overlay adds it.
+
+The call works on its own — deliver it by calling `installPrecedence({ endpoint })`
+once at your app root ([`@precedence-dev/sdk`](https://github.com/precedence-dev/sdk)).
+
+Add `planUrl` to `installPrecedence` and the SDK loads the plan as a **live
+overlay**: it matches each baked call by `psc_id` and lets the plan rename the
+event, narrow its props, add or change the discriminator, or disable it — no
+rebuild. The next `precedence-instrument` run re-bakes the source to match, and
+the overlay for that anchor goes quiet. So plan edits are live immediately and
+converge back into the source on the next build; only a brand-new call site (a
+new anchor) or a newly-surfaced prop needs a build.
+
+`--track "<callee> from <module>"` retargets the call to your own function (the
+callee may be dotted). Then that function is yours to keep matching the plan.
+
+**Synthetic anchors** — links and bare `<button>`s with no handler — have no call
+site to bake into. `precedence-instrument` stamps them with `data-precedence-id`
+and generates a self-contained click-listener module: `--delegated <file>` writes
+it, import it once at your app root. It calls the same `precedence.track`, so the
+overlay applies to it too.
 
 ## Debug a live event: `--explain`
 
-Every emitted event carries `pm_id` (the structural anchor id). Copy one from
-the dashboard and run:
+Every baked call carries `psc_id`. Copy one from the dashboard and run:
 
 ```
-precedence-instrument --plan plan.json --dir src --explain "src/Checkout.tsx#Checkout::form|onSubmit|result_ok"
-precedence-instrument --plan plan.json --dir src --explain "<pm_id>" --json   # structured
+precedence-instrument --plan plan.json --dir src --explain "p_1qzcbxk"
+precedence-instrument --plan plan.json --dir src --explain "<psc_id>" --json   # structured
 ```
 
+(`--explain` also accepts the readable structural id, if your plan is stale.)
+
 It doesn't instrument anything — it traces the id back to its exact fire site
 and reports, per property, the **structural** reasons a value can arrive null
 (out of scope here → baked `undefined`; the branch fires precisely when the
@@ -92,7 +117,7 @@ src/
 ├── generate/
 │   ├── instrument.ts   the resolver + edit primitives + safety wrapping
 │   ├── unplugin.ts      the bundler-plugin delivery path
-│   ├── explain.ts       trace a fired event's pm_id back to its source
+│   ├── explain.ts       trace a fired event's psc_id back to its source
 │   └── cli.ts           the precedence-instrument binary
 ├── discover.ts          resolve --dir/--files/--changed-since to a file list
 └── util.ts              (tiny, no analysis logic — see below)

package/dist/generate/cli.js

@@ -38,9 +38,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * precedence-instrument, CI transform. Splice tracking calls into the source from a
  * plan (the events a PM defined in the picker / viewer "copy events" export).
  *
- *   precedence-instrument --plan plan.json --dir src --track "track from @/lib/analytics"
- *   precedence-instrument --plan plan.json --dir src --track track --apply
- *   precedence-instrument --plan plan.json --dir src --track track --check   # CI: fail if drifted
+ *   precedence-instrument --plan plan.json --dir src --apply           # precedence.track + import
+ *   precedence-instrument --plan plan.json --dir src --check           # CI: fail if drifted
+ *   precedence-instrument --plan plan.json --dir src --track "t from @/lib/analytics" --apply
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -49,20 +49,20 @@ const discover_1 = require("../discover");
 const util_1 = require("../util");
 const instrument_1 = require("./instrument");
 const explain_1 = require("./explain");
-const HELP = `precedence-instrument, splice tracking calls into the source from a plan
+const HELP = `precedence-instrument, bake tracking calls into the source from a plan
 
 USAGE
-  precedence-instrument --plan plan.json --dir src --track "<name> from <module>"
+  precedence-instrument --plan plan.json --dir src --apply
 
 OPTIONS
   --plan <file>      the events export from the picker / viewer  (required)
   --dir <path>       source dir to scan (repeatable)              (required)
-  --track <spec>     direct mode: "track from @/lib/analytics" -> adds an import
-                     "track"                     -> assume it's already in scope / global
-                     (default: console.log, every event logs "[pm] <name>", no import)
-  --emit <mode>      "direct" (default): track("name", { props }) baked in
-                     "runtime": globalThis.__pm?.("<id>", { props }), toggle/rename
-                       become plan edits; needs @precedence-dev/sdk at the app root
+  --track <spec>     the call target — a complete precedence.track("name",
+                     { psc_id, ...props }) call is baked in (a plan overlay in
+                     @precedence-dev/sdk can still rename / retune it live)
+                     (default: "precedence.track from @precedence-dev/sdk", import added)
+                     "myTrack from @/lib/analytics" -> bake into your own fn + import it
+                     "myTrack"                      -> assume it's already in scope
   --types            resolve declared types via the TS checker (needs a tsconfig).
                      Required for callback-edge-rule continuation anchors (mutate onSuccess/
                      onError, .then(f,g)).
@@ -72,16 +72,18 @@ OPTIONS
                      stays reviewable in a diff
   --allow-dirty      let --apply run against a dirty git tree anyway
   --out-dir <dir>    write changed files here instead of in place
-  --runtime <file>   write the delegated click/navigate listener here (for synthetic anchors)
+  --delegated <file> write the synthetic-anchor click listener here (links / bare
+                     buttons — they have no call site); import it once at your app root
   --check            exit 1 if any file would change  (for CI verification)
   --json             machine-readable report to stdout
   --reanchor         don't instrument, repair a plan whose ids stopped resolving
                      (e.g. a component was renamed) by matching on fingerprint,
                      write the fixed plan to --out for review
   --out <file>       where --reanchor writes the repaired plan (default: <plan>.reanchored.json)
-  --explain <pm_id>  don't instrument, trace one pm_id (as seen in the dashboard)
-                     back to its fire site and report, per property, when it can
-                     arrive null. Pair with --json for the structured report.
+  --explain <psc_id> don't instrument, trace one psc_id (the p_… hash seen in the
+                     dashboard, or the readable structural id) back to its fire
+                     site and report, per property, when it can arrive null.
+                     Pair with --json for the structured report.
   -h, --help
 
 EXIT
@@ -94,26 +96,20 @@ const OPTIONS = new Map([
     ["--plan", (o, next) => { o.plan = next(); }],
     ["--dir", (o, next) => { o.paths.push(next()); }],
     ["--track", (o, next) => { o.track = next(); }],
-    ["--emit", (o, next) => {
-            const v = next();
-            if (v !== "direct" && v !== "runtime")
-                fail("--emit must be direct|runtime");
-            o.emit = v;
-        }],
     ["--apply", (o) => { o.apply = true; }],
     ["--allow-dirty", (o) => { o.allowDirty = true; }],
     ["--types", (o) => { o.types = true; }],
     ["--tsconfig", (o, next) => { o.tsconfig = next(); }],
     ["--check", (o) => { o.check = true; }],
     ["--out-dir", (o, next) => { o.outDir = next(); }],
-    ["--runtime", (o, next) => { o.runtime = next(); }],
+    ["--delegated", (o, next) => { o.delegated = next(); }],
     ["--json", (o) => { o.json = true; }],
     ["--reanchor", (o) => { o.reanchor = true; }],
     ["--out", (o, next) => { o.out = next(); }],
     ["--explain", (o, next) => { o.explain = next(); }],
 ]);
 function parseArgs(argv) {
-    const o = { plan: "", paths: [], track: "", emit: "direct", apply: false, allowDirty: false, check: false, types: false, tsconfig: "", outDir: "", json: false, runtime: "", reanchor: false, out: "", explain: "" };
+    const o = { plan: "", paths: [], track: "", apply: false, allowDirty: false, check: false, types: false, tsconfig: "", outDir: "", json: false, delegated: "", reanchor: false, out: "", explain: "" };
     const cur = { i: 0 };
     const next = (a) => { const v = argv[++cur.i]; if (v === undefined)
         fail(`missing value for ${a}`); return v; };
@@ -135,7 +131,7 @@ function parseArgs(argv) {
         fail("--plan is required");
     if (!o.paths.length)
         fail("--dir is required");
-    // --track optional now: direct mode defaults to console.log (in instrument.ts)
+    // --track optional: defaults to precedence.track from @precedence-dev/sdk (in instrument.ts)
     return o;
 }
 /** fill an LCS length table, `dp[i][j]` = LCS of `A[i:]` and `B[j:]`. */
@@ -262,14 +258,14 @@ function printTextReport(r) {
     r.skipped.forEach((x) => process.stderr.write(`  - ${x.event}  skipped: ${x.reason}${x.id ? `  (${x.id})` : ""}\n`));
     process.stdout.write(`\n${added.length} call(s) in ${r.files.length} file(s)${unchanged ? `, ${unchanged} already in place` : ""}, ${r.delegated.length} delegated, ${r.warnings.length} drift, ${r.skipped.length} skipped\n`);
 }
-function emitRuntimeModule(r, o) {
-    if (o.runtime && r.runtimeModule) {
-        fs.mkdirSync(path.dirname(path.resolve(o.runtime)), { recursive: true });
-        fs.writeFileSync(o.runtime, r.runtimeModule);
-        process.stdout.write(`  wrote ${o.runtime}  (${r.delegated.length} delegated event(s), import it once at your app root)\n`);
+function emitDelegatedModule(r, o) {
+    if (o.delegated && r.delegatedModule) {
+        fs.mkdirSync(path.dirname(path.resolve(o.delegated)), { recursive: true });
+        fs.writeFileSync(o.delegated, r.delegatedModule);
+        process.stdout.write(`  wrote ${o.delegated}  (${r.delegated.length} synthetic anchor(s), import it once at your app root)\n`);
     }
-    else if (r.runtimeModule && !o.json) {
-        process.stdout.write(`\n--- delegated listener (pass --runtime <file> to write it) ---\n${r.runtimeModule}\n`);
+    else if (r.delegatedModule && !o.json) {
+        process.stdout.write(`\n--- synthetic-anchor listener (pass --delegated <file> to write it) ---\n${r.delegatedModule}\n`);
     }
 }
 function writeChanges(r, o) {
@@ -302,7 +298,7 @@ function main() {
         return;
     }
     const r = (0, instrument_1.instrument)(inputs, plan, {
-        track: o.track, emit: o.emit, types: o.types, tsconfig: o.tsconfig || undefined,
+        track: o.track, types: o.types, tsconfig: o.tsconfig || undefined,
     });
     if (o.json)
         process.stdout.write(JSON.stringify(r, null, 2) + "\n");
@@ -313,7 +309,7 @@ function main() {
     // longer resolves cleanly against the source, both are CI failures.
     if (o.check)
         process.exit(changed.length || r.skipped.length ? 1 : 0);
-    emitRuntimeModule(r, o);
+    emitDelegatedModule(r, o);
     writeChanges(r, o);
 }
 const VERDICT_MARK = {
@@ -323,8 +319,19 @@ const VERDICT_MARK = {
     "maybe-null": "⚠ may be null",
     "resolves": "· ok",
 };
+/** `--explain` accepts the readable structural id or the baked `p_…` hash; the
+ *  plan maps one to the other. */
+function resolveExplainId(plan, arg) {
+    if (!arg.startsWith("p_"))
+        return arg;
+    for (const ev of plan.events)
+        for (const a of ev.anchors)
+            if ((0, instrument_1.pscId)(a.id) === arg)
+                return a.id;
+    return arg; // let explain() report the miss
+}
 function doExplain(inputs, plan, o) {
-    const r = (0, explain_1.explain)(inputs, plan, o.explain);
+    const r = (0, explain_1.explain)(inputs, plan, resolveExplainId(plan, o.explain));
     if (o.json) {
         process.stdout.write(JSON.stringify(r, null, 2) + "\n");
         process.exit(r.resolved ? 0 : 1);

package/dist/generate/explain.js

@@ -35,11 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.explain = explain;
 /**
- * `precedence-instrument --explain <pm_id>` — the reverse direction of the pipeline.
+ * `precedence-instrument --explain <psc_id>` — the reverse direction of the pipeline.
  *
- * Every emitted event carries `pm_id` (the structural anchor id). Given one seen
- * in the analytics dashboard, this traces it back to the exact fire site and
- * says, per property, whether and when the value can arrive null.
+ * Every emitted event carries `psc_id` (a hash of the structural anchor id; the
+ * plan maps it back). Given one seen in the analytics dashboard, this traces it
+ * to the exact fire site and says, per property, whether and when the value can
+ * arrive null. (The CLI resolves a `p_…` hash to the structural id via the plan
+ * before calling this; `explain()` itself takes the structural id.)
  *
  * Static analysis only. It enumerates the STRUCTURAL reasons a value is absent:
  *   · out of lexical scope at this site   → instrumenter bakes `undefined`
@@ -131,7 +133,7 @@ function anchorFor(plan, id) {
 function whyMiss(loaded, id) {
     const m = id.split("|")[0].match(/^(.+)#([^#]*)::(.+)$/);
     if (!m)
-        return "unrecognised id — copy it from the dashboard's pm_id property verbatim";
+        return "unrecognised id — copy the psc_id from the dashboard verbatim (the p_… hash, or the readable id if the plan is stale)";
     const [, file, comp] = m;
     const L = loaded.find((x) => (0, build_1.norm)(x.file) === (0, build_1.norm)(file) || (0, build_1.norm)(x.file).endsWith("/" + (0, build_1.norm)(file)));
     if (!L)

package/dist/generate/instrument.d.ts

@@ -31,19 +31,14 @@ export interface Plan {
     events: PlanEvent[];
 }
 export interface InstrumentOpts {
-    /**
-     * "direct" (default): inject `track("event_name", { props })` + an import.
-     *   Self-contained, readable, no runtime dependency. To change anything → rebuild.
-     * "runtime": inject `globalThis.__pm?.("<anchor id>", { props })`, no import,
-     *   no static/discriminator props baked in. `@precedence-dev/sdk` (installPrecedence)
-     *   looks the id up in the fetched plan and shapes the event. Toggle / rename /
-     *   static values / prop narrowing become plan edits, no rebuild.
-     */
-    emit?: "direct" | "runtime";
-    /** direct mode only: "<name> from <module>" adds an import; "<name>" assumes global */
+    /** the call target. Default `precedence.track from @precedence-dev/sdk` — a
+     *  complete `precedence.track("event", { psc_id, ...props })` call plus an
+     *  `import { precedence } from "@precedence-dev/sdk"`. The call works on its
+     *  own; loading a plan overlay in the SDK lets a rename / prop-narrow /
+     *  discriminator change / disable take effect before the next build re-bakes it.
+     *  `"<callee> from <module>"` retargets it (callee may be dotted); a bare
+     *  `"<callee>"` assumes it's already in scope. */
     track?: string;
-    /** runtime mode: the global to call (default "globalThis.__pm") */
-    emitGlobal?: string;
     /**
      * resolve declared types via the TS checker. REQUIRED to instrument callback-edge-rule
      * `continuation` anchors (`mutate(x, { onSuccess })`, `p.then(f, g)`) — the
@@ -78,7 +73,6 @@ export interface Delegation {
     element: string;
     ref: string;
     attrs: string[];
-    props: Record<string, string>;
 }
 export interface InstrumentResult {
     files: {
@@ -92,9 +86,11 @@ export interface InstrumentResult {
     /** id resolved, but the code moved on since the plan, injected anyway, verify */
     warnings: Warning[];
     delegated: Delegation[];
-    /** a delegated click/navigate listener for every synthetic anchor, needs
-     *  `data-precedence-id` stamps in the production build (browser/stamp-loader.js) */
-    runtimeModule?: string;
+    /** a self-contained click/navigate listener module for the synthetic anchors
+     *  (links / bare buttons) — they have no call site to bake into. Import it
+     *  once at your app root; it calls `precedence.track`, so the plan overlay
+     *  applies to it too. */
+    delegatedModule?: string;
 }
 /** what a single-module transform returns; null when the plan has nothing here */
 export interface FileInstrumentResult {
@@ -108,9 +104,14 @@ export interface FileInstrumentResult {
 }
 /** every distinct source file a plan references */
 export declare function planFiles(plan: Plan): string[];
-/** every emitted event carries the anchor id under this key, so a value seen in
- *  the dashboard can be traced back to the exact fire site (file/component/branch). */
-export declare const PM_ID_KEY = "pm_id";
+/** reserved property key: the anchor hash on every baked call. It's the key the
+ *  SDK's plan overlay matches on; the readable structural id lives only in the
+ *  plan. */
+export declare const PSC_ID_KEY = "psc_id";
+/** cyrb53 — a tiny 53-bit string hash. `@precedence-dev/sdk` has a byte-for-byte
+ *  copy (`pscId` in its `plan.ts`); the two must stay in sync so the baked
+ *  `psc_id` matches the SDK's plan index. */
+export declare function pscId(structuralId: string): string;
 /**
  * Wrap the raw tracking call so it can never affect the surrounding control
  * flow: a synchronous throw is caught and swallowed, and if it returns a
@@ -121,6 +122,11 @@ export declare const PM_ID_KEY = "pm_id";
  * code does; there is no prior behavior here to disturb.
  */
 export declare function safeStatement(call: string): string;
+/** direct mode's default call target: the SDK's own client. `precedence.track` is
+ *  a contract `@precedence-dev/sdk` owns end-to-end, so the injected call stays
+ *  deterministic without Precedence ever seeing the analytics vendor. Override
+ *  with `--track "<fn> from <module>"` to bake calls into your own function. */
+export declare const DEFAULT_TRACK = "precedence.track from @precedence-dev/sdk";
 export interface ReanchorResult {
     plan: Plan;
     repointed: {
@@ -159,7 +165,9 @@ export declare function instrumentFile(code: string, id: string, plan: Plan, opt
  *  transformed every file. */
 export declare function planDelegations(plan: Plan): Delegation[];
 /** one document-level listener for every synthetic (link / bare-button) anchor,
- *  keyed on the `data-precedence-id="<structural id>"` the transform stamps onto the
- *  same element, one string, produced by one code path, so it can't drift. */
+ *  keyed on the `data-precedence-id="<structural id>"` the transform stamps onto
+ *  the same element. It calls the same `precedence.track`, so a loaded plan
+ *  overlays these clicks exactly as it overlays baked calls. One string, one
+ *  code path, so it can't drift. Import it once at your app root. */
 export declare function buildDelegatedModule(dels: Delegation[], track: string): string;
 export {};

package/dist/generate/instrument.js

@@ -36,8 +36,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PM_ID_KEY = void 0;
+exports.DEFAULT_TRACK = exports.PSC_ID_KEY = void 0;
 exports.planFiles = planFiles;
+exports.pscId = pscId;
 exports.safeStatement = safeStatement;
 exports.reanchor = reanchor;
 exports.instrument = instrument;
@@ -213,9 +214,6 @@ function resolveContextAccessor(ap, via, out, evName) {
 }
 /** how to render one property in the call object */
 function propPart(p, ev, anchor) {
-    const stat = anchor.staticProps || {};
-    if (p in stat)
-        return `${p}: ${JSON.stringify(stat[p])}`;
     const acc = ev.accessors && ev.accessors[p];
     if (typeof acc === "string")
         return acc === p ? p : `${p}: ${acc}`;
@@ -223,31 +221,37 @@ function propPart(p, ev, anchor) {
         return `${p}: undefined /* not in scope here */`;
     return p; // shorthand, the picker checked it resolves
 }
-/** every emitted event carries the anchor id under this key, so a value seen in
- *  the dashboard can be traced back to the exact fire site (file/component/branch). */
-exports.PM_ID_KEY = "pm_id";
-/** direct mode: `track("event_name", { pm_id: "<id>", …everything baked in })` */
-function directCall(fnName, ev, anchor) {
+/** reserved property key: the anchor hash on every baked call. It's the key the
+ *  SDK's plan overlay matches on; the readable structural id lives only in the
+ *  plan. */
+exports.PSC_ID_KEY = "psc_id";
+/** cyrb53 — a tiny 53-bit string hash. `@precedence-dev/sdk` has a byte-for-byte
+ *  copy (`pscId` in its `plan.ts`); the two must stay in sync so the baked
+ *  `psc_id` matches the SDK's plan index. */
+function pscId(structuralId) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < structuralId.length; i++) {
+        const ch = structuralId.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return "p_" + (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/** the baked call: `precedence.track("event_name", { psc_id: "p_…", …the props
+ *  the plan selects })`. The discriminator (`outcome` / `placement`) is *not*
+ *  baked — the SDK's plan overlay adds it, and can rename / narrow / drop the
+ *  call, all by `psc_id`. */
+function emitCall(ev, anchor, callee) {
     const seen = new Set();
-    const parts = [...new Set(ev.properties)].map((p) => { seen.add(p); return propPart(p, ev, anchor); });
-    Object.keys(anchor.staticProps || {}).forEach((k) => { if (!seen.has(k))
-        parts.push(`${k}: ${JSON.stringify((anchor.staticProps || {})[k])}`); });
-    if (!seen.has(exports.PM_ID_KEY) && !(exports.PM_ID_KEY in (anchor.staticProps || {})))
-        parts.unshift(`${exports.PM_ID_KEY}: ${JSON.stringify(anchor.id)}`);
-    return `${fnName}(${JSON.stringify(ev.name)}${obj(parts)})`;
-}
-/** runtime mode: `globalThis.__pm?.("<id>", { …in-scope + ambient props })`.
- *  the id is arg 1 — the runtime layers it onto the payload as `pm_id` at emit
- *  time, along with static / discriminator props from the plan. */
-function runtimeCall(g, ev, anchor) {
-    const skip = new Set([...Object.keys(anchor.staticProps || {}), ...(anchor.missingProps || [])]);
-    const parts = [...new Set(ev.properties)].filter((p) => !skip.has(p)).map((p) => propPart(p, ev, anchor));
-    return `${g}?.(${JSON.stringify(anchor.id)}${obj(parts)})`;
-}
-function emitCall(ev, anchor, opts, fnName) {
-    return opts.emit === "runtime"
-        ? runtimeCall(opts.emitGlobal || "globalThis.__pm", ev, anchor)
-        : directCall(fnName, ev, anchor);
+    const parts = [...new Set(ev.properties)]
+        .filter((p) => !(anchor.staticProps && p in anchor.staticProps))
+        .map((p) => { seen.add(p); return propPart(p, ev, anchor); });
+    if (!seen.has(exports.PSC_ID_KEY))
+        parts.unshift(`${exports.PSC_ID_KEY}: ${JSON.stringify(pscId(anchor.id))}`);
+    return `${callee}(${JSON.stringify(ev.name)}${obj(parts)})`;
 }
 function indentAt(sf, pos) {
     const lineStart = sf.text.lastIndexOf("\n", pos - 1) + 1;
@@ -277,7 +281,7 @@ function assertNever(x) {
 function safeStatement(call) {
     // Promise.resolve covers void / Promise / thenable clients and, unlike `.catch`
     // on an inferred `void`, type-checks in a strict consumer project.
-    return `try { void Promise.resolve(${call}).catch(() => {}); } catch (__pmE) {}`;
+    return `try { void Promise.resolve(${call}).catch(() => {}); } catch (__pscE) {}`;
 }
 /** the same guard, as a single expression — for sites where `call` has to sit
  *  inside a larger expression (a comma operator) rather than stand alone. */
@@ -328,22 +332,34 @@ function planEdit(site, call, sf) {
             return assertNever(site);
     }
 }
+/** direct mode's default call target: the SDK's own client. `precedence.track` is
+ *  a contract `@precedence-dev/sdk` owns end-to-end, so the injected call stays
+ *  deterministic without Precedence ever seeing the analytics vendor. Override
+ *  with `--track "<fn> from <module>"` to bake calls into your own function. */
+exports.DEFAULT_TRACK = "precedence.track from @precedence-dev/sdk";
+/** `"<callee> from <module>"` → `{ callee, importName, spec }`; a bare `"<callee>"`
+ *  → no import. `callee` may be dotted (`precedence.track`, `client.track`); the
+ *  import binds its head (`precedence`, `client`). */
 function parseTrack(track) {
-    const m = track.match(/^\s*([A-Za-z_$][\w$]*)\s+from\s+(.+?)\s*$/);
+    const m = track.match(/^\s*([A-Za-z_$][\w$]*(?:\.[\w$]+)*)\s+from\s+(.+?)\s*$/);
     if (!m)
-        return { fnName: track.trim() || "track", importLine: "", spec: "" };
+        return { callee: track.trim() || "track", importName: "", spec: "" };
     const spec = m[2].replace(/^['"]|['"]$/g, "");
-    return { fnName: m[1], importLine: `import { ${m[1]} } from ${JSON.stringify(spec)};\n`, spec };
+    return { callee: m[1], importName: m[1].split(".")[0], spec };
+}
+function importLineFor(track) {
+    const { importName, spec } = parseTrack(track);
+    return spec ? `import { ${importName} } from ${JSON.stringify(spec)};` : "";
 }
-/** add `import { track } from "spec"` unless the file already has it */
+/** add `import { <head> } from "spec"` unless the file already has that binding */
 function addImport(s, code, track) {
-    const { fnName, spec } = parseTrack(track);
+    const { importName, spec } = parseTrack(track);
     if (!spec)
         return;
-    const re = new RegExp(`import\\s*\\{[^}]*\\b${fnName}\\b[^}]*\\}\\s*from\\s*['"]${spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"]`);
+    const re = new RegExp(`import\\s*\\{[^}]*\\b${importName}\\b[^}]*\\}\\s*from\\s*['"]${spec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"]`);
     if (re.test(code))
         return;
-    const line = `import { ${fnName} } from ${JSON.stringify(spec)};`;
+    const line = importLineFor(track);
     // after the last `import … "spec";` (spans multi-line lists, matches side-effect imports)
     const lastImp = [...code.matchAll(/^import\b[\s\S]*?['"][^'"]*['"]\s*;?/gm)].pop();
     if (lastImp && lastImp.index != null)
@@ -360,35 +376,35 @@ function render(code, edits, id, opts) {
         else
             s.overwrite(e.start, e.end, e.text);
     }
-    // direct mode needs the `track` import, unless the only edits are `data-precedence-id`
-    // stamps. runtime mode calls a global, so it never needs one.
-    if (opts.emit !== "runtime" && edits.some((e) => e.kind !== "stamp"))
-        addImport(s, code, opts.track || "track");
+    // the baked calls need the track import, unless the only edits are
+    // `data-precedence-id` stamps (whose listener module carries its own import).
+    if (edits.some((e) => e.kind !== "stamp"))
+        addImport(s, code, opts.track || exports.DEFAULT_TRACK);
     return {
         code: s.toString(),
         map: s.generateMap({ source: id, hires: true, includeContent: true }),
     };
 }
 /** resolve + verify + plan-edit one anchor, appending its results to `out`. */
-function collectAnchor(a, ev, index, loaded, opts, fnName, out) {
+function collectAnchor(a, ev, index, loaded, opts, callee, out) {
     const ap = resolveAnchor(a, ev, index, loaded, out, opts);
     if (!ap)
         return;
     const drifted = recordDrift(a, ap, ev, out);
     const evR = ev.accessors ? resolveEventAccessors(ev, ap, out) : ev;
-    const call = emitCall(evR, a, opts, fnName);
+    const call = emitCall(evR, a, callee);
     if (ap.site.kind === "delegated")
         applyDelegated(a, ev, ap, out);
     else
         applyInlineEdit(a, ev, ap, call, drifted, out);
 }
 /** resolve + verify + plan-edit every plan anchor (optionally just one file's) */
-function collect(plan, index, loaded, opts, fnName, onlyFile) {
+function collect(plan, index, loaded, opts, callee, onlyFile) {
     const out = { byFile: new Map(), applied: [], skipped: [], warnings: [], delegated: [] };
     for (const ev of plan.events) {
         for (const a of ev.anchors) {
             if (!onlyFile || anchorFile(a.id) === onlyFile) {
-                collectAnchor(a, ev, index, loaded, opts, fnName, out);
+                collectAnchor(a, ev, index, loaded, opts, callee, out);
             }
         }
     }
@@ -435,9 +451,8 @@ function resolveEventAccessors(ev, ap, out) {
 function applyDelegated(a, ev, ap, out) {
     const statKeys = new Set(Object.keys(a.staticProps || {}));
     out.delegated.push({
-        event: ev.name, element: ap.element, ref: ap.id, // the structural id, the runtime join key
+        event: ev.name, element: ap.element, ref: ap.id, // the structural id → hashed to psc_id in the module
         attrs: (ap.autoAttrs && ap.autoAttrs.length ? ap.autoAttrs : (ev.properties || [])).filter((p) => !statKeys.has(p)),
-        props: a.staticProps || {},
     });
     const en = ap.elementNode;
     if (!en || !(ts.isJsxOpeningElement(en) || ts.isJsxSelfClosingElement(en)))
@@ -451,13 +466,12 @@ function applyDelegated(a, ev, ap, out) {
     out.byFile.set(ap.file, list);
 }
 /** true when a previous run already spliced this anchor's call into the file.
- *  Direct mode writes `pm_id: "<id>"`, runtime mode passes the id as arg 1, and
- *  the anchor id is globally unique, so a substring hit is a safe "already done".
- *  An inserting codemod needs this: unlike a pattern-replacing one, an insert
- *  doesn't stop matching on the next pass (cf. addImport's regex guard,
- *  applyDelegated's data-precedence-id check, create-react-app eject's git check). */
+ *  The baked call writes `psc_id: "p_…"` and the hash is globally unique, so a
+ *  substring hit is a safe "already done". An inserting codemod needs this:
+ *  unlike a pattern-replacing one, an insert doesn't stop matching on the next
+ *  pass (cf. addImport's regex guard, applyDelegated's data-precedence-id check). */
 function alreadyInjected(sf, anchorId) {
-    return sf.text.includes(JSON.stringify(anchorId));
+    return sf.text.includes(JSON.stringify(pscId(anchorId)));
 }
 /** an outcome anchor: splice the `track(...)` call at the branch's inject site */
 function applyInlineEdit(a, ev, ap, call, drifted, out) {
@@ -563,8 +577,8 @@ function reanchor(inputs, plan, opts = {}) {
 function instrument(inputs, plan, opts) {
     const { loaded } = (0, build_1.analyze)(inputs, { types: opts.types, tsconfig: opts.tsconfig });
     const index = attachIndex(loaded);
-    const { fnName } = parseTrack(opts.track || "console.log");
-    const c = collect(plan, index, loaded, opts, fnName);
+    const { callee } = parseTrack(opts.track || exports.DEFAULT_TRACK);
+    const c = collect(plan, index, loaded, opts, callee);
     const src = new Map(loaded.map((L) => [(0, build_1.norm)(L.file), L.sf.text]));
     const res = {
         files: [], applied: c.applied, skipped: c.skipped, warnings: c.warnings, delegated: c.delegated,
@@ -587,9 +601,10 @@ function instrument(inputs, plan, opts) {
         }
         res.files.push({ file, before, after: r.code, map: r.map });
     }
-    // direct mode ships a generated PM_DELEGATED module; runtime mode uses @precedence-dev/sdk
-    if (opts.emit !== "runtime" && res.delegated.length) {
-        res.runtimeModule = buildDelegatedModule(res.delegated, opts.track || "track");
+    // synthetic anchors (links / bare buttons) have no call site to bake into —
+    // ship a self-contained listener module for them.
+    if (res.delegated.length) {
+        res.delegatedModule = buildDelegatedModule(res.delegated, opts.track || exports.DEFAULT_TRACK);
     }
     return res;
 }
@@ -602,8 +617,8 @@ function instrumentFile(code, id, plan, opts) {
     if (!loaded.length)
         return { file: planFile, code, map: null, applied: [], warnings: [], skipped: [], delegated: [] };
     const index = attachIndex(loaded);
-    const { fnName } = parseTrack(opts.track || "console.log");
-    const c = collect(plan, index, loaded, opts, fnName, planFile);
+    const { callee } = parseTrack(opts.track || exports.DEFAULT_TRACK);
+    const c = collect(plan, index, loaded, opts, callee, planFile);
     const edits = c.byFile.get((0, build_1.norm)(planFile)) || [...c.byFile.values()][0] || [];
     const r = edits.length ? render(code, edits, id, opts) : { code, map: null };
     return {
@@ -625,17 +640,20 @@ function planDelegations(plan) {
                 event: ev.name, element: a.element || "",
                 ref: a.id, // the structural id, matches what the transform stamps as data-precedence-id
                 attrs: (ev.properties || []).filter((p) => !statKeys.has(p)),
-                props: a.staticProps || {},
             });
         }
     }
     return out;
 }
 /** one document-level listener for every synthetic (link / bare-button) anchor,
- *  keyed on the `data-precedence-id="<structural id>"` the transform stamps onto the
- *  same element, one string, produced by one code path, so it can't drift. */
+ *  keyed on the `data-precedence-id="<structural id>"` the transform stamps onto
+ *  the same element. It calls the same `precedence.track`, so a loaded plan
+ *  overlays these clicks exactly as it overlays baked calls. One string, one
+ *  code path, so it can't drift. Import it once at your app root. */
 function buildDelegatedModule(dels, track) {
-    const { fnName, importLine } = parseTrack(track);
+    const { callee } = parseTrack(track);
+    const imp = importLineFor(track);
+    const importLine = imp ? imp + "\n" : "";
     const rows = dels.map((d) => {
         const readers = d.attrs.map((a) => {
             const dom = a === "label" ? "getAttribute('aria-label')"
@@ -643,13 +661,12 @@ function buildDelegatedModule(dels, track) {
                     : "getAttribute(" + JSON.stringify(a) + ")";
             return `${JSON.stringify(a)}: el.${dom}`;
         });
-        const stat = Object.entries(d.props).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`);
-        const idPart = `${JSON.stringify(exports.PM_ID_KEY)}: ${JSON.stringify(d.ref)}`;
-        return `  ${JSON.stringify(d.ref)}: { name: ${JSON.stringify(d.event)}, props: (el: Element): Record<string, unknown> => ({ ${[idPart].concat(readers, stat).join(", ")} }) },`;
+        const idPart = `${JSON.stringify(exports.PSC_ID_KEY)}: ${JSON.stringify(pscId(d.ref))}`;
+        return `  ${JSON.stringify(d.ref)}: { name: ${JSON.stringify(d.event)}, props: (el: Element): Record<string, unknown> => ({ ${[idPart].concat(readers).join(", ")} }) },`;
     });
     return `${importLine}// generated by precedence-instrument, needs data-precedence-id stamps in the production build
-type PmDelegated = { name: string; props: (el: Element) => Record<string, unknown> };
-const PM_DELEGATED: Record<string, PmDelegated> = {
+type PscDelegated = { name: string; props: (el: Element) => Record<string, unknown> };
+const PSC_DELEGATED: Record<string, PscDelegated> = {
 ${rows.join("\n")}
 };
 if (typeof document !== "undefined") {
@@ -657,8 +674,8 @@ if (typeof document !== "undefined") {
     const el = (e.target instanceof Element) ? e.target.closest("[data-precedence-id]") : null;
     if (!el) return;
     const id = el.getAttribute("data-precedence-id");
-    const hit = id ? PM_DELEGATED[id] : undefined;
-    if (hit) { try { void Promise.resolve(${fnName}(hit.name, hit.props(el))).catch(() => {}); } catch (__pmE) {} }
+    const hit = id ? PSC_DELEGATED[id] : undefined;
+    if (hit) { try { void Promise.resolve(${callee}(hit.name, hit.props(el))).catch(() => {}); } catch (__pscE) {} }
   }, true);
 }
 `;

package/dist/generate/unplugin.d.ts

@@ -2,17 +2,14 @@ import { type Plan, type Skipped } from "./instrument";
 export interface PmInstrumentOptions {
     /** the `copy events` export, a parsed plan, or a path to the JSON file */
     plan: Plan | string;
-    /**
-     * "direct" (default): inject `track(…)` calls + the delegated-listener module.
-     * "runtime": inject `globalThis.__pm?.(id, …)` calls, stamp delegated elements,
-     *   and let `@precedence-dev/sdk` (installPrecedence) do the rest at runtime.
-     *   Toggling / renaming an event no longer needs a rebuild.
-     */
-    emit?: "direct" | "runtime";
-    /** direct mode: "<name> from <module>" adds the import; "<name>" assumes it's global.
-     *  default "console.log", every event logs "[pm] <name>", no import. */
+    /** the call target. Default `precedence.track from @precedence-dev/sdk` — a
+     *  complete `precedence.track("event", { psc_id, ...props })` call plus an
+     *  auto-added import. Load a plan overlay in the SDK to rename / disable /
+     *  retune events before the next build re-bakes them. `"<callee> from
+     *  <module>"` retargets it; a bare `"<callee>"` assumes it's in scope. */
     track?: string;
-    /** direct mode: id for the delegated-listener module (import once at your app root; default "virtual:pm-tracking") */
+    /** id for the synthetic-anchor listener module (import once at your app root;
+     *  default "virtual:pm-tracking") */
     virtualModuleId?: string;
     /** per-file callback, wire drift / skips into your build log or fail the build */
     onReport?: (r: {

package/dist/generate/unplugin.js

@@ -38,8 +38,8 @@ exports.farmPlugin = exports.esbuildPlugin = exports.rspackPlugin = exports.roll
  * precedence-instrument as a bundler transform, the production delivery path.
  *
  * One `transform` hook, adapted to Vite / webpack / Rollup / esbuild / Rspack by
- * unplugin. Source files never change on disk; the `track(…)` calls exist only
- * in the bundle, so instrumentation is idempotent and sourcemap-clean by
+ * unplugin. Source files never change on disk; the `precedence.track(…)` calls
+ * exist only in the bundle, so instrumentation is idempotent and sourcemap-clean by
  * construction, and CI reviews the plan diff, not a machine-rewritten tree.
  *
  * One implementation, six bundlers: per-module `transform(code, id)`, plan/config
@@ -49,19 +49,16 @@ exports.farmPlugin = exports.esbuildPlugin = exports.rspackPlugin = exports.roll
  *   import { webpackPlugin as pmInstrument } from "@precedence-dev/instrument/unplugin";
  *   const nextConfig = {
  *     webpack(config) {
- *       config.plugins.push(pmInstrument({
- *         plan: "./tracking-plan.json",
- *         track: "track from @/lib/analytics",
- *       }));
+ *       config.plugins.push(pmInstrument({ plan: "./tracking-plan.json" }));
  *       return config;
  *     },
  *   };
  *
  *   // vite.config.ts
  *   import { vitePlugin as pmInstrument } from "@precedence-dev/instrument/unplugin";
- *   export default { plugins: [pmInstrument({ plan, track })] };
+ *   export default { plugins: [pmInstrument({ plan })] };
  *
- *   // app entry, ONCE, pulls in the delegated click listener for synthetic anchors
+ *   // app entry, ONCE, pulls in the click listener for synthetic anchors
  *   import "virtual:pm-tracking";
  */
 const fs = __importStar(require("fs"));
@@ -72,7 +69,7 @@ exports.unpluginPmInstrument = (0, unplugin_1.createUnplugin)((options) => {
     const plan = typeof options.plan === "string"
         ? JSON.parse(fs.readFileSync(options.plan, "utf8"))
         : options.plan;
-    const opts = { track: options.track, emit: options.emit }; // track defaults to console.log in instrument.ts
+    const opts = { track: options.track }; // track defaults to precedence.track in instrument.ts
     const files = (0, instrument_1.planFiles)(plan);
     const delegated = (0, instrument_1.planDelegations)(plan); // from the plan alone, no build ordering dependency
     const VID = options.virtualModuleId || "virtual:pm-tracking";
@@ -108,12 +105,9 @@ exports.unpluginPmInstrument = (0, unplugin_1.createUnplugin)((options) => {
         load(id) {
             if (id !== RESOLVED)
                 return null;
-            if (options.emit === "runtime") {
-                return "// runtime mode: import { installPrecedence } from '@precedence-dev/sdk' and call it at your app root instead of importing this\nexport {};\n";
-            }
             return delegated.length
-                ? (0, instrument_1.buildDelegatedModule)(delegated, options.track || "track")
-                : "// precedence: no delegated (synthetic) anchors in the plan\nexport {};\n";
+                ? (0, instrument_1.buildDelegatedModule)(delegated, options.track || instrument_1.DEFAULT_TRACK)
+                : "// precedence: no synthetic (link / bare-button) anchors in the plan\nexport {};\n";
         },
     };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precedence-dev/instrument",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Splice tracking calls into source (or a build) from a plan produced by Precedence's analysis engine. Source-available so anyone can read exactly what code it generates and where it puts it.",
   "license": "FSL-1.1-ALv2",
   "author": "Precedence",
@@ -39,7 +39,7 @@
     "test": "npm run build && node --test \"test/**/*.test.mjs\" && node test/invariants.mjs"
   },
   "dependencies": {
-    "@precedence-dev/cli": "^0.1.0",
+    "@precedence-dev/cli": "^0.2.0",
     "magic-string": "^0.30.21",
     "typescript": "^5.6.3",
     "unplugin": "^2.3.11"