assign-gingerly 0.0.79 → 0.0.81

package/DX/paths.js

@@ -27,6 +27,34 @@
  * The sp tag function uses this to auto-extract path strings from proxies.
  */
 const PATH_SYMBOL = Symbol('assign-gingerly-path');
+function isPathProxy(value) {
+    return !!value && (typeof value === 'object' || typeof value === 'function') && PATH_SYMBOL in value;
+}
+const COMMAND_TOKEN_SUFFIXES = {
+    Each: '?.@each',
+    EqNot: ' =!',
+    PlusEq: ' +=',
+    QMEq: ' ?=',
+    YEq: ' Y=',
+    MinusEq: ' -=',
+    Arrow: ' =>',
+};
+function serializePath(prefix) {
+    return prefix.length > 0 ? `?.${prefix}` : '?.';
+}
+function appendPathSegment(prefix, segment) {
+    return prefix ? `${prefix}?.${segment}` : segment;
+}
+function appendCommandSuffix(prefix, token) {
+    return `${prefix}${COMMAND_TOKEN_SUFFIXES[token]}`;
+}
+function getReservedToken(prop) {
+    if (prop === 'Path' || prop === 'path')
+        return prop;
+    if (prop in COMMAND_TOKEN_SUFFIXES)
+        return prop;
+    return undefined;
+}
 /**
  * Create a proxy for id-ref paths (#[varName]).
  * After the initial #[varName], further property access chains with ?. from the resolved element.
@@ -34,15 +62,23 @@ const PATH_SYMBOL = Symbol('assign-gingerly-path');
  */
 function createIdRefProxy(idRef, options) {
     function handler() { }
+    Object.defineProperty(handler, PATH_SYMBOL, { value: idRef });
     return new Proxy(handler, {
         get(_, prop) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
+            if (prop === 'path' || prop === 'Path' || prop === PATH_SYMBOL) {
                 return idRef;
             }
             if (typeof prop === 'symbol')
                 return undefined;
+            const reservedToken = getReservedToken(prop);
+            if (reservedToken === 'Each') {
+                return createIdRefProxy(appendPathSegment(idRef, '@each'), options);
+            }
+            if (reservedToken && reservedToken !== 'Path' && reservedToken !== 'path') {
+                return createIdRefProxy(appendCommandSuffix(idRef, reservedToken), options);
+            }
             // Chain further path segments after the id ref
-            const chained = `${idRef}?.${String(prop)}`;
+            const chained = appendPathSegment(idRef, String(prop));
             return createIdRefProxy(chained, options);
         },
         apply(_, __, args) {
@@ -53,7 +89,7 @@ function createIdRefProxy(idRef, options) {
                     argStr = 'true';
                 else if (arg === false)
                     argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                else if (isPathProxy(arg)) {
                     const fullPath = arg[PATH_SYMBOL];
                     argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
                 }
@@ -77,14 +113,25 @@ function createPathProxy(prefix, options) {
     const aliasMap = options?.aka;
     // Use a function as the target to enable the apply trap
     function handler() { }
+    Object.defineProperty(handler, PATH_SYMBOL, { value: prefix.length > 0 ? `?.${prefix}` : '?.' });
     return new Proxy(handler, {
         get(_, prop) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return prefix.length > 0 ? `?.${prefix}` : '?.';
+            if (prop === 'path' || prop === 'Path' || prop === PATH_SYMBOL) {
+                return serializePath(prefix);
             }
             // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
             if (typeof prop === 'symbol')
                 return undefined;
+            const reservedToken = getReservedToken(String(prop));
+            if (reservedToken === 'Path' || reservedToken === 'path') {
+                return serializePath(prefix);
+            }
+            if (reservedToken === 'Each') {
+                return createPathProxy(appendPathSegment(prefix, '@each'), options);
+            }
+            if (reservedToken) {
+                return createPathProxy(appendCommandSuffix(prefix, reservedToken), options);
+            }
             let segment = String(prop);
             // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
             if (segment.startsWith('#')) {
@@ -102,7 +149,7 @@ function createPathProxy(prefix, options) {
                     }
                 }
             }
-            const newPath = prefix ? `${prefix}?.${segment}` : segment;
+            const newPath = appendPathSegment(prefix, segment);
             return createPathProxy(newPath, options);
         },
         apply(_, __, args) {
@@ -114,14 +161,14 @@ function createPathProxy(prefix, options) {
                     argStr = 'true';
                 else if (arg === false)
                     argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                else if (isPathProxy(arg)) {
                     // Proxy arg — extract path without '?.' prefix
                     const fullPath = arg[PATH_SYMBOL];
                     argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
                 }
                 else
                     argStr = String(arg);
-                const newPath = prefix ? `${prefix}?.${argStr}` : argStr;
+                const newPath = appendPathSegment(prefix, argStr);
                 return createPathProxy(newPath, options);
             }
             // No args — method called with no arguments, return self
@@ -167,12 +214,12 @@ export function paths(options) {
  * }
  */
 export function set(lhs) {
-    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
+    const lhsStr = isPathProxy(lhs)
         ? lhs[PATH_SYMBOL]
         : String(lhs);
     return {
         to(rhs) {
-            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
+            const rhsStr = isPathProxy(rhs)
                 ? rhs[PATH_SYMBOL]
                 : rhs;
             return { [lhsStr]: rhsStr };
@@ -198,7 +245,7 @@ export function set(lhs) {
  * // { assign: { incrementButton: '?.clone?.q?..increment', ... } }
  */
 export function smoothOver(value) {
-    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
+    if (isPathProxy(value)) {
         return value[PATH_SYMBOL];
     }
     if (Array.isArray(value)) {
@@ -294,13 +341,13 @@ export function sp(strings, ...values) {
             result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Auto-extract path from proxy object
                 result.push(v[PATH_SYMBOL]);
             }
             else if (Array.isArray(v)) {
                 // Nested array — recursively extract paths from proxy elements
-                result.push(v.map(el => el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el));
+                result.push(v.map(el => isPathProxy(el) ? el[PATH_SYMBOL] : el));
             }
             else {
                 result.push(v);
@@ -314,8 +361,10 @@ export function sp(strings, ...values) {
  * e.g., '?.address?.city' → 'city', '?.firstName' → 'firstName'
  */
 function extractPropName(pathStr) {
-    const parts = pathStr.split('?.');
-    return parts[parts.length - 1];
+    const withoutCommand = pathStr.replace(/(?: \+=| =!| \?=| Y=| -=| =>)$/, '');
+    const parts = withoutCommand.split('?.');
+    const last = parts[parts.length - 1];
+    return last === '@each' ? 'Each' : last;
 }
 /**
  * Tagged template literal that produces an array of {prop, val} objects + literal strings.
@@ -349,7 +398,7 @@ export function md(strings, ...values) {
             result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Proxy object → {prop, val}
                 const pathStr = v[PATH_SYMBOL];
                 result.push({ prop: extractPropName(pathStr), val: pathStr });
@@ -357,7 +406,7 @@ export function md(strings, ...values) {
             else if (Array.isArray(v)) {
                 // Nested array — recursively convert proxy elements to {prop, val}
                 result.push(v.map(el => {
-                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
+                    if (isPathProxy(el)) {
                         const pathStr = el[PATH_SYMBOL];
                         return { prop: extractPropName(pathStr), val: pathStr };
                     }
@@ -367,7 +416,7 @@ export function md(strings, ...values) {
             else if (v && typeof v === 'object' && 'prop' in v) {
                 // Developer override object — extract val from proxy if present
                 const processed = { ...v };
-                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
+                if (isPathProxy(processed.val)) {
                     processed.val = processed.val[PATH_SYMBOL];
                 }
                 result.push(processed);

package/DX/paths.ts

@@ -27,21 +27,68 @@
  * Symbol used internally to detect path proxy objects.
  * The sp tag function uses this to auto-extract path strings from proxies.
  */
-const PATH_SYMBOL = Symbol('assign-gingerly-path');
+const PATH_SYMBOL = Symbol('assign-gingerly-path');
+
+function isPathProxy(value: unknown): value is { [PATH_SYMBOL]: string } {
+    return !!value && (typeof value === 'object' || typeof value === 'function') && PATH_SYMBOL in value;
+}
+
+const COMMAND_TOKEN_SUFFIXES = {
+    Each: '?.@each',
+    EqNot: ' =!',
+    PlusEq: ' +=',
+    QMEq: ' ?=',
+    YEq: ' Y=',
+    MinusEq: ' -=',
+    Arrow: ' =>',
+} as const;
+
+type CommandToken = keyof typeof COMMAND_TOKEN_SUFFIXES;
+
+function serializePath(prefix: string): string {
+    return prefix.length > 0 ? `?.${prefix}` : '?.';
+}
+
+function appendPathSegment(prefix: string, segment: string): string {
+    return prefix ? `${prefix}?.${segment}` : segment;
+}
+
+function appendCommandSuffix(prefix: string, token: CommandToken): string {
+    return `${prefix}${COMMAND_TOKEN_SUFFIXES[token]}`;
+}
+
+function getReservedToken(prop: string): CommandToken | 'Path' | 'path' | undefined {
+    if (prop === 'Path' || prop === 'path') return prop;
+    if (prop in COMMAND_TOKEN_SUFFIXES) return prop as CommandToken;
+    return undefined;
+}
 
 /**
- * Type that maps an object type to a proxy where every property access
- * returns either a deeper proxy (for object properties) or a terminal
- * with a `.path` string accessor — while providing full autocomplete.
- * Enhanced: also callable (for method call syntax).
- */
-export type PathProxy<T> = {
-    [K in keyof T]-?: T[K] extends ((...args: any[]) => infer R)
-        ? ((...args: any[]) => PathProxy<NonNullable<R>> & { readonly path: string }) & PathProxy<NonNullable<R>> & { readonly path: string }
-        : T[K] extends (object | undefined | null)
-            ? PathProxy<NonNullable<T[K]>> & { readonly path: string } & ((...args: any[]) => PathProxy<any> & { readonly path: string })
-            : { readonly path: string } & ((...args: any[]) => PathProxy<any> & { readonly path: string });
-} & { readonly path: string } & ((...args: any[]) => PathProxy<any> & { readonly path: string });
+ * Type that maps an object type to a proxy where every property access
+ * returns either a deeper proxy (for object properties) or a terminal
+ * with a serialized path string accessor — while providing full autocomplete.
+ * Enhanced: also callable (for method call syntax) and includes reserved
+ * command markers such as `Each`, `EqNot`, and `PlusEq`.
+ */
+export type PathProxyCore = {
+    readonly Path: string;
+    readonly path: string;
+    readonly Each: PathProxy<any>;
+    readonly EqNot: PathProxy<any>;
+    readonly PlusEq: PathProxy<any>;
+    readonly QMEq: PathProxy<any>;
+    readonly YEq: PathProxy<any>;
+    readonly MinusEq: PathProxy<any>;
+    readonly Arrow: PathProxy<any>;
+};
+
+export type PathProxy<T> = {
+    [K in keyof T]-?: T[K] extends ((...args: any[]) => infer R)
+        ? ((...args: any[]) => PathProxy<NonNullable<R>> & PathProxyCore) & PathProxy<NonNullable<R>> & PathProxyCore
+        : T[K] extends (object | undefined | null)
+            ? PathProxy<NonNullable<T[K]>> & PathProxyCore & ((...args: any[]) => PathProxy<any> & PathProxyCore)
+            : PathProxyCore & ((...args: any[]) => PathProxy<any> & PathProxyCore);
+} & PathProxyCore & ((...args: any[]) => PathProxy<any> & PathProxyCore);
 
 /**
  * Options for paths proxy creation.
@@ -58,26 +105,35 @@ export interface PathsOptions {
  * After the initial #[varName], further property access chains with ?. from the resolved element.
  * .path returns the #[varName] prefix (optionally with further ?. path).
  */
-function createIdRefProxy(idRef: string, options?: PathsOptions): any {
-    function handler() {}
-    return new Proxy(handler, {
-        get(_, prop: string | symbol) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return idRef;
-            }
-            if (typeof prop === 'symbol') return undefined;
-
-            // Chain further path segments after the id ref
-            const chained = `${idRef}?.${String(prop)}`;
-            return createIdRefProxy(chained, options);
-        },
-        apply(_, __, args) {
-            if (args.length > 0) {
-                const arg = args[0];
+function createIdRefProxy(idRef: string, options?: PathsOptions): any {
+    function handler() {}
+    Object.defineProperty(handler, PATH_SYMBOL, { value: idRef });
+    return new Proxy(handler, {
+        get(_, prop: string | symbol) {
+            if (prop === 'path' || prop === 'Path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
+            if (typeof prop === 'symbol') return undefined;
+
+            const reservedToken = getReservedToken(prop);
+            if (reservedToken === 'Each') {
+                return createIdRefProxy(appendPathSegment(idRef, '@each'), options);
+            }
+            if (reservedToken && reservedToken !== 'Path' && reservedToken !== 'path') {
+                return createIdRefProxy(appendCommandSuffix(idRef, reservedToken), options);
+            }
+
+            // Chain further path segments after the id ref
+            const chained = appendPathSegment(idRef, String(prop));
+            return createIdRefProxy(chained, options);
+        },
+        apply(_, __, args) {
+            if (args.length > 0) {
+                const arg = args[0];
                 let argStr: string;
                 if (arg === true) argStr = 'true';
                 else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                else if (isPathProxy(arg)) {
                     const fullPath = arg[PATH_SYMBOL] as string;
                     argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
                 }
@@ -98,60 +154,72 @@ function createIdRefProxy(idRef: string, options?: PathsOptions): any {
  * When `aka` is provided, property names that match an alias *value* are output
  * using the alias *key* instead (reverse alias).
  */
-function createPathProxy(prefix: string, options?: PathsOptions): any {
-    const aliasMap = options?.aka;
-
-    // Use a function as the target to enable the apply trap
-    function handler() {}
-
-    return new Proxy(handler, {
-        get(_, prop: string | symbol) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return prefix.length > 0 ? `?.${prefix}` : '?.';
-            }
-            // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
-            if (typeof prop === 'symbol') return undefined;
-
-            let segment = String(prop);
-
-            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
-            if (segment.startsWith('#')) {
-                const varName = segment.substring(1);
-                const idRef = `#[${varName}]`;
+function createPathProxy(prefix: string, options?: PathsOptions): any {
+    const aliasMap = options?.aka;
+
+    // Use a function as the target to enable the apply trap
+    function handler() {}
+    Object.defineProperty(handler, PATH_SYMBOL, { value: prefix.length > 0 ? `?.${prefix}` : '?.' });
+
+    return new Proxy(handler, {
+        get(_, prop: string | symbol) {
+            if (prop === 'path' || prop === 'Path' || prop === PATH_SYMBOL) {
+                return serializePath(prefix);
+            }
+            // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
+            if (typeof prop === 'symbol') return undefined;
+
+            const reservedToken = getReservedToken(String(prop));
+            if (reservedToken === 'Path' || reservedToken === 'path') {
+                return serializePath(prefix);
+            }
+            if (reservedToken === 'Each') {
+                return createPathProxy(appendPathSegment(prefix, '@each'), options);
+            }
+            if (reservedToken) {
+                return createPathProxy(appendCommandSuffix(prefix, reservedToken), options);
+            }
+
+            let segment = String(prop);
+
+            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
+            if (segment.startsWith('#')) {
+                const varName = segment.substring(1);
+                const idRef = `#[${varName}]`;
                 // Return a proxy that starts from this id ref (can chain further with ?.)
                 return createIdRefProxy(idRef, options);
             }
 
             // Apply reverse alias: if prop matches an alias value, use the alias key
-            if (aliasMap) {
-                for (const [alias, target] of Object.entries(aliasMap)) {
-                    if (target === segment) { segment = alias; break; }
-                }
-            }
-
-            const newPath = prefix ? `${prefix}?.${segment}` : segment;
-            return createPathProxy(newPath, options);
-        },
-        apply(_, __, args) {
-            // Method call syntax: $.querySelector('.username') → extends path with the argument
-            if (args.length > 0) {
+            if (aliasMap) {
+                for (const [alias, target] of Object.entries(aliasMap)) {
+                    if (target === segment) { segment = alias; break; }
+                }
+            }
+
+            const newPath = appendPathSegment(prefix, segment);
+            return createPathProxy(newPath, options);
+        },
+        apply(_, __, args) {
+            // Method call syntax: $.querySelector('.username') → extends path with the argument
+            if (args.length > 0) {
                 const arg = args[0];
                 let argStr: string;
                 if (arg === true) argStr = 'true';
                 else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
-                    // Proxy arg — extract path without '?.' prefix
-                    const fullPath = arg[PATH_SYMBOL] as string;
-                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
-                }
-                else argStr = String(arg);
-
-                const newPath = prefix ? `${prefix}?.${argStr}` : argStr;
-                return createPathProxy(newPath, options);
-            }
-            // No args — method called with no arguments, return self
-            return createPathProxy(prefix, options);
-        }
+                else if (isPathProxy(arg)) {
+                    // Proxy arg — extract path without '?.' prefix
+                    const fullPath = arg[PATH_SYMBOL] as string;
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else argStr = String(arg);
+
+                const newPath = appendPathSegment(prefix, argStr);
+                return createPathProxy(newPath, options);
+            }
+            // No args — method called with no arguments, return self
+            return createPathProxy(prefix, options);
+        }
     });
 }
 
@@ -193,13 +261,13 @@ export function paths<T>(options?: PathsOptions): PathProxy<T> {
  *     count: 1
  * }
  */
-export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
-    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
-        ? lhs[PATH_SYMBOL]
-        : String(lhs);
+export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
+    const lhsStr = isPathProxy(lhs)
+        ? lhs[PATH_SYMBOL]
+        : String(lhs);
     return {
         to(rhs: any): Record<string, any> {
-            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
+            const rhsStr = isPathProxy(rhs)
                 ? rhs[PATH_SYMBOL]
                 : rhs;
             return { [lhsStr]: rhsStr };
@@ -225,9 +293,9 @@ export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
  * });
  * // { assign: { incrementButton: '?.clone?.q?..increment', ... } }
  */
-export function smoothOver(value: any): any {
-    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
-        return value[PATH_SYMBOL];
+export function smoothOver(value: any): any {
+    if (isPathProxy(value)) {
+        return value[PATH_SYMBOL];
     }
     if (Array.isArray(value)) {
         return value.map(smoothOver);
@@ -328,13 +396,13 @@ export function sp(strings: TemplateStringsArray, ...values: any[]): any[] {
         if (strings[i]) result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Auto-extract path from proxy object
                 result.push(v[PATH_SYMBOL]);
             } else if (Array.isArray(v)) {
                 // Nested array — recursively extract paths from proxy elements
                 result.push(v.map(el =>
-                    el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el
+                    isPathProxy(el) ? el[PATH_SYMBOL] : el
                 ));
             } else {
                 result.push(v);
@@ -348,10 +416,12 @@ export function sp(strings: TemplateStringsArray, ...values: any[]): any[] {
  * Extract the last segment from a `?.`-prefixed path string.
  * e.g., '?.address?.city' → 'city', '?.firstName' → 'firstName'
  */
-function extractPropName(pathStr: string): string {
-    const parts = pathStr.split('?.');
-    return parts[parts.length - 1];
-}
+function extractPropName(pathStr: string): string {
+    const withoutCommand = pathStr.replace(/(?: \+=| =!| \?=| Y=| -=| =>)$/, '');
+    const parts = withoutCommand.split('?.');
+    const last = parts[parts.length - 1];
+    return last === '@each' ? 'Each' : last;
+}
 
 /**
  * Tagged template literal that produces an array of {prop, val} objects + literal strings.
@@ -384,14 +454,14 @@ export function md(strings: TemplateStringsArray, ...values: any[]): any[] {
         if (strings[i]) result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Proxy object → {prop, val}
                 const pathStr = v[PATH_SYMBOL] as string;
                 result.push({ prop: extractPropName(pathStr), val: pathStr });
             } else if (Array.isArray(v)) {
                 // Nested array — recursively convert proxy elements to {prop, val}
                 result.push(v.map(el => {
-                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
+                    if (isPathProxy(el)) {
                         const pathStr = el[PATH_SYMBOL] as string;
                         return { prop: extractPropName(pathStr), val: pathStr };
                     }
@@ -400,7 +470,7 @@ export function md(strings: TemplateStringsArray, ...values: any[]): any[] {
             } else if (v && typeof v === 'object' && 'prop' in v) {
                 // Developer override object — extract val from proxy if present
                 const processed = { ...v };
-                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
+                if (isPathProxy(processed.val)) {
                     processed.val = processed.val[PATH_SYMBOL];
                 }
                 result.push(processed);

package/README.md

@@ -4400,9 +4400,10 @@ export default {
 **How `paths` works:**
 
 - `paths<T>()` creates a deeply-proxied object typed as `T`
-- Every property access returns a deeper proxy (e.g., `$.address.city`)
-- `.path` extracts the `?.`-prefixed string: `$.address.city.path` → `'?.address?.city'`
-- Inside `sp` template literals, `.path` is not needed — proxy objects are auto-detected
+- Every property access returns a deeper proxy (e.g., `$.address.city`)
+- Capitalized reserved tokens like `.Each` and `.EqNot` normalize into command syntax
+- `.Path` extracts the `?.`-prefixed string: `$.address.city.Path` → `'?.address?.city'`
+- Inside `sp` template literals, `.Path` is not needed — proxy objects are auto-detected
 
 **How `sp` works:**
 
@@ -4421,19 +4422,19 @@ const value = sp`${$.lastName}${[', ', $.middleName]}, ${$.firstName}`;
 // ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
 ```
 
-**Using `.path` outside of `sp`:**
+**Using `.Path` outside of `sp`:**
 
 When you need the path string in a non-`sp` context (object keys, plain arrays, other expressions):
 
 ```TypeScript
 const $ = paths<Person>();
 
-$.lastName.path           // '?.lastName'
-$.address.city.path       // '?.address?.city'
+$.lastName.Path           // '?.lastName'
+$.address.city.Path       // '?.address?.city'
 
 // As an object key:
 const pattern = {
-    [$.textContent.path]: '?.firstName'  // '?.textContent': '?.firstName'
+    [$.textContent.Path]: '?.firstName'  // '?.textContent': '?.firstName'
 };
 ```
 
@@ -4473,7 +4474,7 @@ md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`
 | `sp` | `'?.firstName'` (path string) | `builtIns.join` |
 | `md` | `{ prop: 'firstName', val: '?.firstName' }` | `builtIns.microDataJoin` |
 
-Both auto-detect path proxies (no `.path` needed inside template literals) and preserve nested arrays for optional segments.
+Both auto-detect path proxies (no `.Path` needed inside template literals) and preserve nested arrays for optional segments.
 
 ## Cached Element Resolution with `#[x]` and `pin`