@bgub/fig-refresh 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ben Gubler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @bgub/fig-refresh
+
+Fast Refresh runtime for [Fig](https://github.com/bgub/fig). It tracks
+component families across module re-evaluations and installs the refresh
+handler that lets the reconciler swap implementations in place while
+preserving state.
+
+This package is wiring, not an API you call from application code: build
+tooling (such as `@bgub/fig-vite`) injects `register`/`setSignature` calls
+into transformed modules and drives `performRefresh` on hot updates.
+
+See the repository's `concepts/` directory for the underlying contracts.
+
+## Installation
+
+```bash
+pnpm add @bgub/fig-refresh
+```
+
+Fig packages are ESM-only and require Node `^20.19.0 || >=22.12.0` for Node runtime entry
+points.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { RefreshUpdate } from "@bgub/fig-reconciler/refresh";
+//#region src/index.d.ts
+declare function register(type: unknown, id: string): void;
+declare function setSignature(type: unknown, key: string, forceReset?: boolean): void;
+declare function injectScheduleRefresh(scheduleRefresh: (update: RefreshUpdate) => void): void;
+declare function performRefresh(): RefreshUpdate | null;
+//#endregion
+export { injectScheduleRefresh, performRefresh, register, setSignature };

package/dist/index.js

@@ -0,0 +1,83 @@
+import { setRefreshHandler } from "@bgub/fig-reconciler/refresh";
+//#region src/index.ts
+const familiesByType = /* @__PURE__ */ new WeakMap();
+const familiesById = /* @__PURE__ */ new Map();
+const signatures = /* @__PURE__ */ new WeakMap();
+const scheduleRefreshFns = /* @__PURE__ */ new Set();
+const unscheduledRefreshes = [];
+let pendingUpdates = [];
+let installed = false;
+function asKey(type) {
+	return typeof type === "function" || typeof type === "object" && type !== null ? type : null;
+}
+function ensureInstalled() {
+	if (installed) return;
+	installed = true;
+	setRefreshHandler(resolveFamilyByType);
+}
+function resolveFamilyByType(type) {
+	const key = asKey(type);
+	return key === null ? void 0 : familiesByType.get(key);
+}
+function register(type, id) {
+	ensureInstalled();
+	const key = asKey(type);
+	if (key === null || familiesByType.has(key)) return;
+	let family = familiesById.get(id);
+	if (family === void 0) {
+		family = { current: type };
+		familiesById.set(id, family);
+	} else pendingUpdates.push([family, key]);
+	familiesByType.set(key, family);
+}
+function setSignature(type, key, forceReset = false) {
+	const target = asKey(type);
+	if (target !== null) signatures.set(target, {
+		forceReset,
+		key
+	});
+}
+function injectScheduleRefresh(scheduleRefresh) {
+	ensureInstalled();
+	scheduleRefreshFns.add(scheduleRefresh);
+	for (const update of unscheduledRefreshes) scheduleRefresh(update);
+	unscheduledRefreshes.length = 0;
+}
+function performRefresh() {
+	if (pendingUpdates.length === 0) return null;
+	const updates = pendingUpdates;
+	pendingUpdates = [];
+	const updatedFamilies = /* @__PURE__ */ new Set();
+	const staleFamilies = /* @__PURE__ */ new Set();
+	for (const [family, nextType] of updates) {
+		const prevType = family.current;
+		family.current = nextType;
+		if (isSignatureStale(prevType, nextType)) staleFamilies.add(family);
+		else updatedFamilies.add(family);
+	}
+	for (const family of staleFamilies) updatedFamilies.delete(family);
+	const update = {
+		staleFamilies,
+		updatedFamilies
+	};
+	if (scheduleRefreshFns.size === 0) {
+		unscheduledRefreshes.push(update);
+		return update;
+	}
+	for (const scheduleRefresh of scheduleRefreshFns) scheduleRefresh(update);
+	return update;
+}
+function isSignatureStale(prevType, nextType) {
+	const prevKey = asKey(prevType);
+	const nextKey = asKey(nextType);
+	const prev = prevKey === null ? void 0 : signatures.get(prevKey);
+	const next = nextKey === null ? void 0 : signatures.get(nextKey);
+	if (next?.forceReset === true) return true;
+	if (prev === void 0 && next === void 0) return false;
+	if (prev === void 0 || next === void 0) return true;
+	return prev.key !== next.key;
+}
+//#endregion
+export { injectScheduleRefresh, performRefresh, register, setSignature };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  type RefreshFamily,\n  type RefreshUpdate,\n  setRefreshHandler,\n} from \"@bgub/fig-reconciler/refresh\";\n\n// The Fig Fast Refresh runtime. A bundler transform (dev only) registers each\n// component version under a stable id and records its hook signature, then calls\n// performRefresh() from an import.meta.hot.accept handler. The runtime groups\n// versions into families, decides which can re-render in place vs must remount,\n// and drives the reconciler.\n\ninterface Signature {\n  forceReset: boolean;\n  key: string;\n}\n\nconst familiesByType = new WeakMap<object, RefreshFamily>();\nconst familiesById = new Map<string, RefreshFamily>();\nconst signatures = new WeakMap<object, Signature>();\nconst scheduleRefreshFns = new Set<(update: RefreshUpdate) => void>();\nconst unscheduledRefreshes: RefreshUpdate[] = [];\nlet pendingUpdates: Array<[RefreshFamily, object]> = [];\nlet installed = false;\n\nfunction asKey(type: unknown): object | null {\n  return typeof type === \"function\" ||\n    (typeof type === \"object\" && type !== null)\n    ? (type as object)\n    : null;\n}\n\n// Install the reconciler handler lazily so importing the runtime has no effect\n// until something actually registers (keeps it tree-shakeable / prod-safe).\nfunction ensureInstalled(): void {\n  if (installed) return;\n  installed = true;\n  setRefreshHandler(resolveFamilyByType);\n}\n\nfunction resolveFamilyByType(type: unknown): RefreshFamily | undefined {\n  const key = asKey(type);\n  return key === null ? undefined : familiesByType.get(key);\n}\n\n// Register a component version under a stable id (e.g. \"src/App.tsx#App\"). The\n// first version creates a family; later versions of the same id queue an update.\nexport function register(type: unknown, id: string): void {\n  ensureInstalled();\n  const key = asKey(type);\n  if (key === null || familiesByType.has(key)) return;\n\n  let family = familiesById.get(id);\n  if (family === undefined) {\n    family = { current: type };\n    familiesById.set(id, family);\n  } else {\n    pendingUpdates.push([family, key]);\n  }\n  familiesByType.set(key, family);\n}\n\n// Record a component's hook signature. Differing signatures between versions\n// (or forceReset) mean a remount; identical signatures re-render in place.\nexport function setSignature(\n  type: unknown,\n  key: string,\n  forceReset = false,\n): void {\n  const target = asKey(type);\n  if (target !== null) signatures.set(target, { forceReset, key });\n}\n\n// Connect a renderer's scheduleRefresh (e.g. from @bgub/fig-dom). The app's dev\n// bootstrap calls this once.\nexport function injectScheduleRefresh(\n  scheduleRefresh: (update: RefreshUpdate) => void,\n): void {\n  ensureInstalled();\n  scheduleRefreshFns.add(scheduleRefresh);\n  for (const update of unscheduledRefreshes) scheduleRefresh(update);\n  unscheduledRefreshes.length = 0;\n}\n\n// Apply queued registrations: advance each family to its newest version, bucket\n// it as updated (re-render in place) or stale (remount), and drive the renderers.\nexport function performRefresh(): RefreshUpdate | null {\n  if (pendingUpdates.length === 0) return null;\n\n  const updates = pendingUpdates;\n  pendingUpdates = [];\n\n  const updatedFamilies = new Set<RefreshFamily>();\n  const staleFamilies = new Set<RefreshFamily>();\n\n  for (const [family, nextType] of updates) {\n    const prevType = family.current;\n    family.current = nextType;\n    if (isSignatureStale(prevType, nextType)) staleFamilies.add(family);\n    else updatedFamilies.add(family);\n  }\n\n  // If a family was edited more than once and any edit was stale, prefer remount.\n  for (const family of staleFamilies) updatedFamilies.delete(family);\n\n  const update: RefreshUpdate = { staleFamilies, updatedFamilies };\n  if (scheduleRefreshFns.size === 0) {\n    unscheduledRefreshes.push(update);\n    return update;\n  }\n  for (const scheduleRefresh of scheduleRefreshFns) scheduleRefresh(update);\n  return update;\n}\n\nfunction isSignatureStale(prevType: unknown, nextType: unknown): boolean {\n  const prevKey = asKey(prevType);\n  const nextKey = asKey(nextType);\n  const prev = prevKey === null ? undefined : signatures.get(prevKey);\n  const next = nextKey === null ? undefined : signatures.get(nextKey);\n\n  if (next?.forceReset === true) return true;\n  // Neither version recorded a signature: treat as a safe in-place update.\n  if (prev === undefined && next === undefined) return false;\n  // One has a signature and the other doesn't, or the keys differ: remount.\n  if (prev === undefined || next === undefined) return true;\n  return prev.key !== next.key;\n}\n"],"mappings":";;AAiBA,MAAM,iCAAiB,IAAI,QAA+B;AAC1D,MAAM,+BAAe,IAAI,IAA2B;AACpD,MAAM,6BAAa,IAAI,QAA2B;AAClD,MAAM,qCAAqB,IAAI,IAAqC;AACpE,MAAM,uBAAwC,CAAC;AAC/C,IAAI,iBAAiD,CAAC;AACtD,IAAI,YAAY;AAEhB,SAAS,MAAM,MAA8B;CAC3C,OAAO,OAAO,SAAS,cACpB,OAAO,SAAS,YAAY,SAAS,OACnC,OACD;AACN;AAIA,SAAS,kBAAwB;CAC/B,IAAI,WAAW;CACf,YAAY;CACZ,kBAAkB,mBAAmB;AACvC;AAEA,SAAS,oBAAoB,MAA0C;CACrE,MAAM,MAAM,MAAM,IAAI;CACtB,OAAO,QAAQ,OAAO,KAAA,IAAY,eAAe,IAAI,GAAG;AAC1D;AAIA,SAAgB,SAAS,MAAe,IAAkB;CACxD,gBAAgB;CAChB,MAAM,MAAM,MAAM,IAAI;CACtB,IAAI,QAAQ,QAAQ,eAAe,IAAI,GAAG,GAAG;CAE7C,IAAI,SAAS,aAAa,IAAI,EAAE;CAChC,IAAI,WAAW,KAAA,GAAW;EACxB,SAAS,EAAE,SAAS,KAAK;EACzB,aAAa,IAAI,IAAI,MAAM;CAC7B,OACE,eAAe,KAAK,CAAC,QAAQ,GAAG,CAAC;CAEnC,eAAe,IAAI,KAAK,MAAM;AAChC;AAIA,SAAgB,aACd,MACA,KACA,aAAa,OACP;CACN,MAAM,SAAS,MAAM,IAAI;CACzB,IAAI,WAAW,MAAM,WAAW,IAAI,QAAQ;EAAE;EAAY;CAAI,CAAC;AACjE;AAIA,SAAgB,sBACd,iBACM;CACN,gBAAgB;CAChB,mBAAmB,IAAI,eAAe;CACtC,KAAK,MAAM,UAAU,sBAAsB,gBAAgB,MAAM;CACjE,qBAAqB,SAAS;AAChC;AAIA,SAAgB,iBAAuC;CACrD,IAAI,eAAe,WAAW,GAAG,OAAO;CAExC,MAAM,UAAU;CAChB,iBAAiB,CAAC;CAElB,MAAM,kCAAkB,IAAI,IAAmB;CAC/C,MAAM,gCAAgB,IAAI,IAAmB;CAE7C,KAAK,MAAM,CAAC,QAAQ,aAAa,SAAS;EACxC,MAAM,WAAW,OAAO;EACxB,OAAO,UAAU;EACjB,IAAI,iBAAiB,UAAU,QAAQ,GAAG,cAAc,IAAI,MAAM;OAC7D,gBAAgB,IAAI,MAAM;CACjC;CAGA,KAAK,MAAM,UAAU,eAAe,gBAAgB,OAAO,MAAM;CAEjE,MAAM,SAAwB;EAAE;EAAe;CAAgB;CAC/D,IAAI,mBAAmB,SAAS,GAAG;EACjC,qBAAqB,KAAK,MAAM;EAChC,OAAO;CACT;CACA,KAAK,MAAM,mBAAmB,oBAAoB,gBAAgB,MAAM;CACxE,OAAO;AACT;AAEA,SAAS,iBAAiB,UAAmB,UAA4B;CACvE,MAAM,UAAU,MAAM,QAAQ;CAC9B,MAAM,UAAU,MAAM,QAAQ;CAC9B,MAAM,OAAO,YAAY,OAAO,KAAA,IAAY,WAAW,IAAI,OAAO;CAClE,MAAM,OAAO,YAAY,OAAO,KAAA,IAAY,WAAW,IAAI,OAAO;CAElE,IAAI,MAAM,eAAe,MAAM,OAAO;CAEtC,IAAI,SAAS,KAAA,KAAa,SAAS,KAAA,GAAW,OAAO;CAErD,IAAI,SAAS,KAAA,KAAa,SAAS,KAAA,GAAW,OAAO;CACrD,OAAO,KAAK,QAAQ,KAAK;AAC3B"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bgub/fig-refresh",
+  "version": "0.0.1",
+  "description": "Fig Fast Refresh runtime (HMR)",
+  "keywords": [],
+  "homepage": "https://github.com/bgub/fig",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "author": "Ben Gubler <nebrelbug@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bgub/fig",
+    "directory": "packages/fig-refresh"
+  },
+  "bugs": {
+    "url": "https://github.com/bgub/fig/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@bgub/fig-reconciler": "0.0.1"
+  },
+  "devDependencies": {
+    "@bgub/fig-reconciler": "0.0.1"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown --config ../../tsdown.config.ts && node ../../scripts/strip-declaration-map-comments.mjs dist",
+    "test": "vitest run --config ../../vite.config.ts src"
+  }
+}