@foldkit/vite-plugin 0.10.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @foldkit/vite-plugin
 
-Vite plugin for Foldkit that enables hot module reloading with model preservation.
+Vite plugin for Foldkit: view identity branding for the differ, plus hot module reloading with model preservation.
 
 ## Installation
 
@@ -26,7 +26,15 @@ export default defineConfig({
 })
 ```
 
-## What it does
+## View identity
+
+Foldkit's differ tracks two independent kinds of identity: user keys, which match siblings in dynamic lists, and a framework-managed identity, which decides whether a matched position is still the same thing. When the producing view function changes, the differ replaces the node instead of patching it, so DOM state cannot bleed across an identity change. Branches rendered inline by one view function share that function's identity and patch in place, exactly as same-type elements do in React; extracting the branches into named view functions makes them identity boundaries.
+
+This plugin supplies that identity. At build time, in dev and production alike, it wraps every function return in your application modules with a branding call that stamps returned vnodes with the function's id (module path plus function name), set-if-absent. Identity therefore attaches at view-function boundaries, and any branching syntax behaves the same: if/else, ternaries, Effect Match, switch statements, and pattern-matching libraries are all equivalent, because identity belongs to the function that produced the subtree, not to the branch that selected it.
+
+Foldkit core modules are never instrumented, and functions that never return vnodes are wrapped inertly. Builds without this plugin fall back to positional matching plus keys, where branch points need hand-written keys.
+
+## Hot module reloading
 
 When you save a file during development, the plugin:
 

package/dist/brandDist.d.ts

@@ -0,0 +1,19 @@
+/** Result of {@link brandDistDirectory}: per-file branding counts. */
+export type BrandDistResult = Readonly<{
+    brandedCount: number;
+    skippedCount: number;
+}>;
+/**
+ * Brands every compiled `.js` file under `<packageRoot>/dist` in place by
+ * applying {@link transformViewIdentity} to each one, so packages such as
+ * `@foldkit/ui` and `@foldkit/devtools` ship dist output whose view functions
+ * carry identities without requiring consumers to run the Vite plugin over
+ * `node_modules`.
+ *
+ * Module ids follow the `/virtual/<packageName>/<relativePath>` scheme
+ * against a `/virtual` synthetic root, so identities are stable across
+ * machines and never leak build-host paths. Files the transform returns
+ * `null` for (no functions, or already branded) are counted as skipped.
+ */
+export declare const brandDistDirectory: (packageRoot: string, packageName: string) => BrandDistResult;
+//# sourceMappingURL=brandDist.d.ts.map

package/dist/brandDist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brandDist.d.ts","sourceRoot":"","sources":["../src/brandDist.ts"],"names":[],"mappings":"AAQA,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,MAAM,EACnB,aAAa,MAAM,KAClB,eAyBF,CAAA"}

package/dist/brandDist.js

@@ -0,0 +1,40 @@
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { transformViewIdentity } from './viewIdentity.js';
+const SYNTHETIC_ROOT = '/virtual';
+const SCRIPT_FILE_EXTENSION = '.js';
+/**
+ * Brands every compiled `.js` file under `<packageRoot>/dist` in place by
+ * applying {@link transformViewIdentity} to each one, so packages such as
+ * `@foldkit/ui` and `@foldkit/devtools` ship dist output whose view functions
+ * carry identities without requiring consumers to run the Vite plugin over
+ * `node_modules`.
+ *
+ * Module ids follow the `/virtual/<packageName>/<relativePath>` scheme
+ * against a `/virtual` synthetic root, so identities are stable across
+ * machines and never leak build-host paths. Files the transform returns
+ * `null` for (no functions, or already branded) are counted as skipped.
+ */
+export const brandDistDirectory = (packageRoot, packageName) => {
+    const distDirectory = join(packageRoot, 'dist');
+    const relativeScriptPaths = readdirSync(distDirectory, {
+        recursive: true,
+        encoding: 'utf8',
+    })
+        .filter(relativePath => relativePath.endsWith(SCRIPT_FILE_EXTENSION))
+        .sort();
+    const brandFlags = relativeScriptPaths.map(relativePath => {
+        const absolutePath = join(distDirectory, relativePath);
+        const posixRelativePath = relativePath.split(sep).join('/');
+        const syntheticId = `${SYNTHETIC_ROOT}/${packageName}/${posixRelativePath}`;
+        const code = readFileSync(absolutePath, 'utf8');
+        const result = transformViewIdentity(code, syntheticId, SYNTHETIC_ROOT);
+        if (result === null) {
+            return false;
+        }
+        writeFileSync(absolutePath, result.code);
+        return true;
+    });
+    const brandedCount = brandFlags.filter(isBranded => isBranded).length;
+    return { brandedCount, skippedCount: brandFlags.length - brandedCount };
+};

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import type { Plugin } from 'vite';
+export { type BrandDistResult, brandDistDirectory } from './brandDist.js';
+export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
 export type FoldkitPluginOptions = Readonly<{
     /**
@@ -9,5 +11,11 @@ export type FoldkitPluginOptions = Readonly<{
      */
     devToolsMcpPort?: number;
 }>;
-export declare const foldkit: (options?: FoldkitPluginOptions) => Plugin;
+/**
+ * Foldkit's Vite plugin set: the view-identity branding transform (dev and
+ * build) plus the HMR bridge with state preservation and the optional
+ * DevTools MCP relay (dev only). Returned as an array; Vite flattens nested
+ * plugin arrays, so `plugins: [foldkit()]` keeps working.
+ */
+export declare const foldkit: (options?: FoldkitPluginOptions) => Array<Plugin>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,MAAM,EAAkC,MAAM,MAAM,CAAA;AAGlE,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AAgiBF,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,MAqC5D,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,MAAM,EAAkC,MAAM,MAAM,CAAA;AAKlE,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AAgiBF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CAuCxE,CAAA"}

package/dist/index.js

@@ -4,6 +4,9 @@ import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import { foldkitViewIdentity } from './viewIdentity.js';
+export { brandDistDirectory } from './brandDist.js';
+export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // NOTE: Vite's dep optimizer scans the consumer's source for `effect`
 // imports and pre-bundles only those exports into a single `effect.js`
 // blob. It does not follow imports through workspace/node_modules
@@ -279,9 +282,15 @@ const main = (server, events, options) => Effect.gen(function* () {
     yield* Stream.fromQueue(events).pipe(Stream.runForEach(event => dispatchEvent(server, state, event)));
 });
 // PLUGIN ENTRY
+/**
+ * Foldkit's Vite plugin set: the view-identity branding transform (dev and
+ * build) plus the HMR bridge with state preservation and the optional
+ * DevTools MCP relay (dev only). Returned as an array; Vite flattens nested
+ * plugin arrays, so `plugins: [foldkit()]` keeps working.
+ */
 export const foldkit = (options = {}) => {
     const events = Effect.runSync(Queue.unbounded());
-    return {
+    const hmrPlugin = {
         name: 'foldkit-hmr',
         apply: 'serve',
         config: userConfig => ({
@@ -307,4 +316,5 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
+    return [foldkitViewIdentity(), hmrPlugin];
 };

package/dist/viewIdentity.d.ts

@@ -0,0 +1,63 @@
+import { type SourceMap } from 'magic-string';
+import { type Plugin } from 'vite';
+/** Result of {@link transformViewIdentity}: rewritten code plus a source map. */
+export type ViewIdentityTransformResult = Readonly<{
+    code: string;
+    map: SourceMap;
+}>;
+/**
+ * Brands the return value of every function in a module with that function's
+ * identity via `brandViewResult` from `foldkit/brand`.
+ *
+ * Identities are `${posixRelativePathFromRoot}#${functionName}`, with the
+ * function name taken from, in order: the function's own id (declarations and
+ * named function expressions), the variable a function expression is bound
+ * to, the non-computed key of an
+ * object property, class method, or class field, `default` for an
+ * export-default function, the member name of an `x.y = fn` assignment, and
+ * `anonymous` otherwise. Duplicate names within a module are disambiguated in
+ * source order with `~2`, `~3`, and so on, so ids are fully deterministic.
+ *
+ * Expression-body arrows have their body wrapped in the branding call; block
+ * bodies have every `return` argument belonging directly to the function
+ * wrapped (nested functions instrument their own returns, and bare `return`
+ * is untouched). Branding is set-if-absent on vnodes at runtime, so wrapping
+ * every function, including async and generator functions and functions that
+ * never produce a vnode, is inert outside view results.
+ *
+ * Skips foldkit core modules: if the element factory's own returns were
+ * branded, every vnode would carry an identity at construction and
+ * set-if-absent would neutralize the feature. Core under `node_modules` is
+ * always skipped. The plugin resolves the installed foldkit package and passes
+ * `isFoldkitCoreResolved`; when it resolved, the plugin's precise package-root
+ * gate is authoritative and the coarse `packages/foldkit/` path fragment is
+ * left to the resolution-failed fallback, so a consumer whose own path merely
+ * contains that segment is still branded.
+ *
+ * Skips modules whose parsed program imports or re-exports the
+ * `foldkit/brand` specifier: packages such as `@foldkit/ui` and
+ * `@foldkit/devtools` brand their dist at package build time, and pnpm
+ * symlink realpaths can surface that dist outside `node_modules`, where the
+ * module-id checks alone would let a build wrap the same returns twice. A
+ * module that merely mentions the specifier in a comment or string is still
+ * branded; the raw-text check is only a fast negative prefilter.
+ *
+ * Returns `null` when the module needs no changes.
+ */
+export declare const transformViewIdentity: (code: string, id: string, root: string, options?: Readonly<{
+    isFoldkitCoreResolved?: boolean;
+}>) => ViewIdentityTransformResult | null;
+/**
+ * Vite plugin that applies {@link transformViewIdentity} to application
+ * modules in both dev and build. Skips `node_modules`, virtual modules,
+ * non-script files, and foldkit core itself, resolved from the config root so
+ * that configs aliasing `foldkit` straight into `packages/foldkit/src` are
+ * excluded too. `@foldkit/ui` and `@foldkit/devtools` modules are branded on
+ * purpose.
+ *
+ * Also pins `foldkit/brand` to the installed package's brand module via a
+ * `resolve.alias` entry, so the injected import keeps resolving in configs
+ * whose own `foldkit` alias would otherwise swallow the subpath.
+ */
+export declare const foldkitViewIdentity: () => Plugin;
+//# sourceMappingURL=viewIdentity.d.ts.map

package/dist/viewIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewIdentity.d.ts","sourceRoot":"","sources":["../src/viewIdentity.ts"],"names":[],"mappings":"AAAA,OAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAI1D,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,MAAM,CAAA;AAwZ5C,iFAAiF;AACjF,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,SAAS,CAAA;CACf,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,MAAM,MAAM,EACZ,UAAU,QAAQ,CAAC;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,KACtD,2BAA2B,GAAG,IAyChC,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAAO,MA0CtC,CAAA"}

package/dist/viewIdentity.js

@@ -0,0 +1,443 @@
+import MagicString from 'magic-string';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative, resolve, sep } from 'node:path';
+import { parseAst } from 'vite';
+const BRAND_MODULE_SPECIFIER = 'foldkit/brand';
+const BRAND_EXPORT_NAME = 'brandViewResult';
+const BRAND_IMPORT_ALIAS = '__foldkitBrandViewResult';
+const FIRST_ALIAS_SUFFIX = 2;
+const FIRST_DUPLICATE_NAME_SUFFIX = 2;
+const DEFAULT_EXPORT_FUNCTION_NAME = 'default';
+const ANONYMOUS_FUNCTION_NAME = 'anonymous';
+const FOLDKIT_PACKAGE_NAME = 'foldkit';
+const FOLDKIT_CORE_PATH_FRAGMENT = 'packages/foldkit/';
+const VIRTUAL_MODULE_PREFIX = '\0';
+const SCRIPT_FILE_PATTERN = /\.(?:ts|tsx|js|jsx|mts|mjs)$/;
+const isAstNode = (value) => typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    typeof value.type === 'string';
+const isIdentifier = (node) => node.type === 'Identifier';
+const isPrivateIdentifier = (node) => node.type === 'PrivateIdentifier';
+const isLiteral = (node) => node.type === 'Literal';
+const isMemberExpression = (node) => node.type === 'MemberExpression';
+const isAssignmentExpression = (node) => node.type === 'AssignmentExpression';
+const FUNCTION_NODE_TYPES = new Set([
+    'ArrowFunctionExpression',
+    'FunctionExpression',
+    'FunctionDeclaration',
+]);
+const isFunctionNode = (node) => FUNCTION_NODE_TYPES.has(node.type);
+const isReturnStatement = (node) => node.type === 'ReturnStatement';
+const isVariableDeclarator = (node) => node.type === 'VariableDeclarator';
+const NAMED_VALUE_NODE_TYPES = new Set([
+    'Property',
+    'MethodDefinition',
+    'PropertyDefinition',
+]);
+const isNamedValueNode = (node) => NAMED_VALUE_NODE_TYPES.has(node.type) &&
+    isAstNode(node['key']) &&
+    isAstNode(node['value']);
+const walkChildNodes = (node, visitChild) => {
+    for (const [fieldName, fieldValue] of Object.entries(node)) {
+        if (fieldName === 'parent') {
+            continue;
+        }
+        if (isAstNode(fieldValue)) {
+            visitChild(fieldValue);
+        }
+        else if (Array.isArray(fieldValue)) {
+            for (const element of fieldValue) {
+                if (isAstNode(element)) {
+                    visitChild(element);
+                }
+            }
+        }
+    }
+};
+const parseProgram = (code) => {
+    try {
+        const program = parseAst(code);
+        if (isAstNode(program)) {
+            return program;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+};
+// ELIGIBILITY
+const stripQuery = (id) => {
+    const [pathWithoutQuery] = id.split('?');
+    return pathWithoutQuery ?? id;
+};
+const toPosixPath = (filePath) => filePath.split(sep).join('/');
+const NODE_MODULES_SEGMENT_PATTERN = /(?:^|\/)node_modules(?:\/|$)/;
+const BRAND_MODULE_STATEMENT_TYPES = new Set([
+    'ImportDeclaration',
+    'ExportNamedDeclaration',
+    'ExportAllDeclaration',
+]);
+const isBrandModuleStatement = (statement) => {
+    if (!BRAND_MODULE_STATEMENT_TYPES.has(statement.type)) {
+        return false;
+    }
+    const source = statement['source'];
+    return (isAstNode(source) &&
+        isLiteral(source) &&
+        source.value === BRAND_MODULE_SPECIFIER);
+};
+const isAlreadyBranded = (program) => {
+    const body = program['body'];
+    if (!Array.isArray(body)) {
+        return false;
+    }
+    return body.some(statement => isAstNode(statement) && isBrandModuleStatement(statement));
+};
+const isEligibleModuleId = (id, isFoldkitCoreResolved) => {
+    if (id.startsWith(VIRTUAL_MODULE_PREFIX)) {
+        return false;
+    }
+    const strippedId = stripQuery(id);
+    const normalizedId = toPosixPath(strippedId);
+    if (NODE_MODULES_SEGMENT_PATTERN.test(normalizedId)) {
+        return false;
+    }
+    if (!SCRIPT_FILE_PATTERN.test(strippedId)) {
+        return false;
+    }
+    // NOTE: the unanchored `packages/foldkit/` fragment is a best-effort
+    // fallback, applied only when the installed foldkit package could not be
+    // resolved. When it was resolved, the plugin's precise `foldkitPackageRoot`
+    // gate already excluded core, so re-applying the fragment here would wrongly
+    // un-brand a consumer whose own app path merely contains the segment (a
+    // workspace named `foldkit`, a vendored fork holding app code).
+    if (isFoldkitCoreResolved) {
+        return true;
+    }
+    return !normalizedId.includes(FOLDKIT_CORE_PATH_FRAGMENT);
+};
+const collectFunctionNodes = (program) => {
+    const functionNodes = [];
+    const parentByNode = new Map();
+    const visitNode = (node) => {
+        if (isFunctionNode(node)) {
+            functionNodes.push(node);
+        }
+        walkChildNodes(node, child => {
+            parentByNode.set(child, node);
+            visitNode(child);
+        });
+    };
+    visitNode(program);
+    const orderedFunctionNodes = [...functionNodes].sort((first, second) => first.start - second.start);
+    return { functionNodes: orderedFunctionNodes, parentByNode };
+};
+const namedKeyText = (key) => {
+    if (isIdentifier(key) || isPrivateIdentifier(key)) {
+        return key.name;
+    }
+    if (isLiteral(key) && typeof key.value === 'string') {
+        return key.value;
+    }
+    return undefined;
+};
+const rawFunctionName = (functionNode, parentByNode) => {
+    if (functionNode.id !== null &&
+        functionNode.id !== undefined &&
+        isIdentifier(functionNode.id)) {
+        return functionNode.id.name;
+    }
+    const parent = parentByNode.get(functionNode);
+    if (parent === undefined) {
+        return ANONYMOUS_FUNCTION_NAME;
+    }
+    if (isVariableDeclarator(parent) &&
+        parent.init === functionNode &&
+        isIdentifier(parent.id)) {
+        return parent.id.name;
+    }
+    if (isNamedValueNode(parent) &&
+        parent.value === functionNode &&
+        !parent.computed) {
+        return namedKeyText(parent.key) ?? ANONYMOUS_FUNCTION_NAME;
+    }
+    if (parent.type === 'ExportDefaultDeclaration') {
+        return DEFAULT_EXPORT_FUNCTION_NAME;
+    }
+    if (isAssignmentExpression(parent) &&
+        parent.right === functionNode &&
+        isMemberExpression(parent.left) &&
+        !parent.left.computed &&
+        isIdentifier(parent.left.property)) {
+        return parent.left.property.name;
+    }
+    return ANONYMOUS_FUNCTION_NAME;
+};
+const assignFunctionIds = (functionNodes, parentByNode, modulePath) => {
+    const functionIds = new Map();
+    const occurrenceCountsByName = new Map();
+    for (const functionNode of functionNodes) {
+        const functionName = rawFunctionName(functionNode, parentByNode);
+        const occurrenceCount = (occurrenceCountsByName.get(functionName) ?? 0) + 1;
+        occurrenceCountsByName.set(functionName, occurrenceCount);
+        const uniqueFunctionName = occurrenceCount < FIRST_DUPLICATE_NAME_SUFFIX
+            ? functionName
+            : `${functionName}~${occurrenceCount}`;
+        functionIds.set(functionNode, `${modulePath}#${uniqueFunctionName}`);
+    }
+    return functionIds;
+};
+const ownReturnArguments = (functionBody) => {
+    const returnArguments = [];
+    const collectFromNode = (node) => {
+        if (isFunctionNode(node)) {
+            return;
+        }
+        if (isReturnStatement(node)) {
+            if (node.argument !== null && node.argument !== undefined) {
+                returnArguments.push(node.argument);
+            }
+            return;
+        }
+        walkChildNodes(node, collectFromNode);
+    };
+    walkChildNodes(functionBody, collectFromNode);
+    return returnArguments;
+};
+const wrapTargets = (functionNode) => {
+    if (functionNode.body.type === 'BlockStatement') {
+        return ownReturnArguments(functionNode.body);
+    }
+    return [functionNode.body];
+};
+const collectWraps = (functionNodes, functionIds) => {
+    const wraps = [];
+    for (const functionNode of functionNodes) {
+        const functionId = functionIds.get(functionNode);
+        if (functionId === undefined) {
+            continue;
+        }
+        for (const target of wrapTargets(functionNode)) {
+            wraps.push({ target, functionId });
+        }
+    }
+    return wraps;
+};
+const isDirectiveStatement = (node) => node.type === 'ExpressionStatement' && typeof node['directive'] === 'string';
+const hashbangEndOffset = (program) => {
+    const hashbang = program['hashbang'];
+    if (isAstNode(hashbang)) {
+        return hashbang.end;
+    }
+    return 0;
+};
+const importInsertionOffset = (program) => {
+    const body = program['body'];
+    if (!Array.isArray(body)) {
+        return hashbangEndOffset(program);
+    }
+    let offset = hashbangEndOffset(program);
+    for (const statement of body) {
+        if (!isAstNode(statement) || !isDirectiveStatement(statement)) {
+            break;
+        }
+        offset = statement.end;
+    }
+    return offset;
+};
+const uniqueBrandAlias = (code) => {
+    if (!code.includes(BRAND_IMPORT_ALIAS)) {
+        return BRAND_IMPORT_ALIAS;
+    }
+    for (let suffix = FIRST_ALIAS_SUFFIX;; suffix += 1) {
+        const candidate = `${BRAND_IMPORT_ALIAS}${suffix}`;
+        if (!code.includes(candidate)) {
+            return candidate;
+        }
+    }
+};
+/**
+ * Brands the return value of every function in a module with that function's
+ * identity via `brandViewResult` from `foldkit/brand`.
+ *
+ * Identities are `${posixRelativePathFromRoot}#${functionName}`, with the
+ * function name taken from, in order: the function's own id (declarations and
+ * named function expressions), the variable a function expression is bound
+ * to, the non-computed key of an
+ * object property, class method, or class field, `default` for an
+ * export-default function, the member name of an `x.y = fn` assignment, and
+ * `anonymous` otherwise. Duplicate names within a module are disambiguated in
+ * source order with `~2`, `~3`, and so on, so ids are fully deterministic.
+ *
+ * Expression-body arrows have their body wrapped in the branding call; block
+ * bodies have every `return` argument belonging directly to the function
+ * wrapped (nested functions instrument their own returns, and bare `return`
+ * is untouched). Branding is set-if-absent on vnodes at runtime, so wrapping
+ * every function, including async and generator functions and functions that
+ * never produce a vnode, is inert outside view results.
+ *
+ * Skips foldkit core modules: if the element factory's own returns were
+ * branded, every vnode would carry an identity at construction and
+ * set-if-absent would neutralize the feature. Core under `node_modules` is
+ * always skipped. The plugin resolves the installed foldkit package and passes
+ * `isFoldkitCoreResolved`; when it resolved, the plugin's precise package-root
+ * gate is authoritative and the coarse `packages/foldkit/` path fragment is
+ * left to the resolution-failed fallback, so a consumer whose own path merely
+ * contains that segment is still branded.
+ *
+ * Skips modules whose parsed program imports or re-exports the
+ * `foldkit/brand` specifier: packages such as `@foldkit/ui` and
+ * `@foldkit/devtools` brand their dist at package build time, and pnpm
+ * symlink realpaths can surface that dist outside `node_modules`, where the
+ * module-id checks alone would let a build wrap the same returns twice. A
+ * module that merely mentions the specifier in a comment or string is still
+ * branded; the raw-text check is only a fast negative prefilter.
+ *
+ * Returns `null` when the module needs no changes.
+ */
+export const transformViewIdentity = (code, id, root, options) => {
+    if (!isEligibleModuleId(id, options?.isFoldkitCoreResolved ?? false)) {
+        return null;
+    }
+    const program = parseProgram(code);
+    if (program === null) {
+        return null;
+    }
+    if (code.includes(BRAND_MODULE_SPECIFIER) && isAlreadyBranded(program)) {
+        return null;
+    }
+    const { functionNodes, parentByNode } = collectFunctionNodes(program);
+    const modulePath = toPosixPath(relative(root, stripQuery(id)));
+    const functionIds = assignFunctionIds(functionNodes, parentByNode, modulePath);
+    const wraps = collectWraps(functionNodes, functionIds);
+    if (wraps.length === 0) {
+        return null;
+    }
+    const brandAlias = uniqueBrandAlias(code);
+    const sourceText = new MagicString(code);
+    // NOTE: applied in descending target order so that when a nested wrap ends
+    // exactly where its enclosing wrap ends (`return () => x`), the inner
+    // closer is appended first and the calls nest correctly.
+    const orderedWraps = [...wraps].sort((first, second) => second.target.start - first.target.start);
+    for (const { target, functionId } of orderedWraps) {
+        sourceText.appendLeft(target.start, `${brandAlias}((`);
+        sourceText.appendRight(target.end, `), ${JSON.stringify(functionId)})`);
+    }
+    const importStatement = `import { ${BRAND_EXPORT_NAME} as ${brandAlias} } from '${BRAND_MODULE_SPECIFIER}'\n`;
+    const insertionOffset = importInsertionOffset(program);
+    if (insertionOffset === 0) {
+        sourceText.prepend(importStatement);
+    }
+    else {
+        sourceText.appendLeft(insertionOffset, `\n${importStatement}`);
+    }
+    return {
+        code: sourceText.toString(),
+        map: sourceText.generateMap({ hires: 'boundary' }),
+    };
+};
+// RESOLUTION
+// NOTE: `requireFromRoot.resolve('foldkit')` cannot produce a path here:
+// foldkit's export map is ESM-only, so resolving it under require conditions
+// throws ERR_PACKAGE_PATH_NOT_EXPORTED. Walking the require resolution
+// candidate directories locates the package without touching the export map.
+const resolveFoldkitPackageRoot = (root) => {
+    const requireFromRoot = createRequire(resolve(root, 'noop.js'));
+    const candidateDirectories = requireFromRoot.resolve.paths(FOLDKIT_PACKAGE_NAME) ?? [];
+    for (const candidateDirectory of candidateDirectories) {
+        const packageDirectory = join(candidateDirectory, FOLDKIT_PACKAGE_NAME);
+        if (existsSync(join(packageDirectory, 'package.json'))) {
+            try {
+                return realpathSync(packageDirectory);
+            }
+            catch {
+                return packageDirectory;
+            }
+        }
+    }
+    return undefined;
+};
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const resolveBrandModulePath = (root) => {
+    const packageRoot = resolveFoldkitPackageRoot(root);
+    if (packageRoot === undefined) {
+        return undefined;
+    }
+    try {
+        const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+        if (!isRecord(packageJson) || !isRecord(packageJson['exports'])) {
+            return undefined;
+        }
+        const brandExportEntry = packageJson['exports']['./brand'];
+        const importTarget = isRecord(brandExportEntry)
+            ? brandExportEntry['import']
+            : brandExportEntry;
+        if (typeof importTarget !== 'string') {
+            return undefined;
+        }
+        const brandModulePath = join(packageRoot, importTarget);
+        if (existsSync(brandModulePath)) {
+            return brandModulePath;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const isUnderDirectory = (posixPath, posixDirectory) => posixPath === posixDirectory || posixPath.startsWith(`${posixDirectory}/`);
+// PLUGIN
+/**
+ * Vite plugin that applies {@link transformViewIdentity} to application
+ * modules in both dev and build. Skips `node_modules`, virtual modules,
+ * non-script files, and foldkit core itself, resolved from the config root so
+ * that configs aliasing `foldkit` straight into `packages/foldkit/src` are
+ * excluded too. `@foldkit/ui` and `@foldkit/devtools` modules are branded on
+ * purpose.
+ *
+ * Also pins `foldkit/brand` to the installed package's brand module via a
+ * `resolve.alias` entry, so the injected import keeps resolving in configs
+ * whose own `foldkit` alias would otherwise swallow the subpath.
+ */
+export const foldkitViewIdentity = () => {
+    let resolvedRoot = process.cwd();
+    let foldkitPackageRoot;
+    return {
+        name: 'foldkit:view-identity',
+        config: userConfig => {
+            const brandModulePath = resolveBrandModulePath(userConfig.root ?? process.cwd());
+            if (brandModulePath === undefined) {
+                return undefined;
+            }
+            // NOTE: returned as an array because Vite's mergeAlias puts array
+            // entries from a plugin ahead of the user's aliases; object-form
+            // entries would land after a user's bare `foldkit` alias and the
+            // injected specifier would be rewritten into a nonexistent path.
+            return {
+                resolve: {
+                    alias: [
+                        { find: BRAND_MODULE_SPECIFIER, replacement: brandModulePath },
+                    ],
+                },
+            };
+        },
+        configResolved: config => {
+            resolvedRoot = config.root;
+            const packageRoot = resolveFoldkitPackageRoot(config.root);
+            foldkitPackageRoot =
+                packageRoot === undefined ? undefined : toPosixPath(packageRoot);
+        },
+        transform: (code, id) => {
+            if (foldkitPackageRoot !== undefined &&
+                isUnderDirectory(toPosixPath(stripQuery(id)), foldkitPackageRoot)) {
+                return null;
+            }
+            return transformViewIdentity(code, id, resolvedRoot, {
+                isFoldkitCoreResolved: foldkitPackageRoot !== undefined,
+            });
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Vite plugin for Foldkit hot module reloading with state preservation",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,20 +16,24 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-beta.88",
+    "effect": "4.0.0-beta.97",
     "foldkit": "^0",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {
+    "magic-string": "^0.30.21",
     "ws": "^8.21.0"
   },
   "devDependencies": {
+    "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
-    "effect": "4.0.0-beta.88",
+    "effect": "4.0.0-beta.97",
+    "happy-dom": "^20.10.4",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
-    "foldkit": "0.117.0"
+    "vitest": "^4.1.9",
+    "foldkit": "0.130.0"
   },
   "keywords": [
     "vite",
@@ -55,6 +59,7 @@
     "clean": "rimraf dist *.tsbuildinfo",
     "build": "pnpm run clean && tsc -b",
     "watch": "tsc -b --watch",
-    "typecheck": "tsc -b --noEmit"
+    "typecheck": "tsc -b --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
   }
 }