@symbo.ls/utils 3.14.774 → 3.14.776

package/sharedLibraries.js

@@ -1,6 +1,8 @@
 'use strict'
 
 import { isObject, isString } from './types.js'
+import { isProtectedElementMethod } from './keys.js'
+import { isLoudDevRuntime } from './env.js'
 
 const DEFAULT_LIBRARY_OWNER = 'system'
 
@@ -271,7 +273,68 @@ export const isWrappedLibrary = (entry) =>
 const wrappedLibraryRef = (entry) =>
   entry.library !== undefined ? entry.library : (entry.key ?? entry.name)
 
-const mergeOneLibrary = (context, sharedLib, ignore) => {
+/**
+ * A library's `methods` never replace a PROTECTED built-in element method
+ * (FW-LIBRARY-METHODS-CANNOT-SHADOW-BUILTIN-ELEMENT-METHODS-1).
+ *
+ * `@symbo.ls/element` layers `context.methods` over its built-in element methods
+ * (getContextProto) and `el.call(name)` reads `context.methods` first, so a
+ * library key named `getRoot` / `getRootState` / … used to replace the built-in
+ * on every element of the consuming app, silently — and kept replacing it after
+ * the framework fixed the built-in. Measured on a live app: a library's
+ * pre-FW-GETROOT `getRoot` copy answered undefined inside installed modules and
+ * every module popover was dead with no error.
+ *
+ * So the merge refuses such a key on both branches and the built-in wins —
+ * except for the OVERRIDE POINTS (keys.js ELEMENT_METHOD_OVERRIDE_POINTS: the
+ * logging hooks log / warn / error / verbose), which merge like any library
+ * method: a library's "log and continue" versions are what its consumers rely
+ * on, and no element semantics depend on them. The APP's OWN `methods` are
+ * untouched (they were in the bag before any library merged) and win over
+ * both. One dev warning per refused name for the page.
+ */
+const _warnedBuiltinMethods = new Set()
+
+// Test-only: forget which names already warned.
+export const __resetBuiltinMethodWarnings = () => {
+  _warnedBuiltinMethods.clear()
+}
+
+const warnRefusedBuiltinMethods = (label, names) => {
+  const fresh = names.filter((n) => !_warnedBuiltinMethods.has(n))
+  if (!fresh.length) return
+  for (const n of fresh) _warnedBuiltinMethods.add(n)
+  if (!isLoudDevRuntime()) return
+  console.warn(
+    `[smbls] shared library "${label}" ships ${fresh.map((n) => `methods.${n}`).join(', ')} — ` +
+    `named like a built-in element method. Refused: the built-in wins; a library cannot ` +
+    `replace an element method on the consuming app. If the app wants this version, ` +
+    `declare it in the app's OWN methods.`
+  )
+}
+
+// The library's `methods` bag without protected built-in names, for the
+// wholesale-copy branch. Same reference when there is nothing to drop (the
+// common case — no allocation, exactly as before); otherwise a copy, because
+// the library's own bag is shared by every consumer and is never edited.
+// A name the consumer ignores (`methods/<name>` in skip) is dropped by
+// copyWithNestedIgnores anyway and is not reported as refused.
+const withoutProtectedMethods = (bag, skip, refused) => {
+  let copy = null
+  for (const k in bag) {
+    if (!isProtectedElementMethod(k)) continue
+    if (!skip.has(`methods/${k}`)) refused.push(k)
+    if (!copy) {
+      copy = {}
+      for (const j in bag) {
+        if (!isProtectedElementMethod(j)) copy[j] = bag[j]
+      }
+    }
+  }
+  return copy || bag
+}
+
+const mergeOneLibrary = (context, sharedLib, ignore, label = 'library') => {
   // A library can declare parts of itself private via `sharedLibIgnore` on
   // its own context — same path grammar as the consumer-side `ignoreList`
   // (top-level keys or nested 'components/Header'). A library serving its
@@ -285,6 +348,7 @@ const mergeOneLibrary = (context, sharedLib, ignore) => {
   const skip = libIgnore.size
     ? new Set([...ignore, ...libIgnore])
     : ignore
+  const refusedMethods = []
   for (const key in sharedLib) {
     if (!Object.prototype.hasOwnProperty.call(sharedLib, key)) continue
     // merge directives, not library content
@@ -307,6 +371,14 @@ const mergeOneLibrary = (context, sharedLib, ignore) => {
       } else {
         for (const k in sharedLib[key]) {
           if (skip.has(`${key}/${k}`)) continue // nested skip: 'components/Header'
+          if (key === 'methods' && isProtectedElementMethod(k)) {
+            // The built-in wins. An app-own key of that name is the app's
+            // declared override and stays — nothing to report for it. The
+            // override points (log / warn / error / verbose) are not protected
+            // and fall through to the normal add-missing merge below.
+            if (!(k in context[key])) refusedMethods.push(k)
+            continue
+          }
           if (!(k in context[key])) {
             context[key][k] = sharedLib[key][k]
           } else if (isStubPhantom(key, context[key][k]) && !isStubPhantom(key, sharedLib[key][k])) {
@@ -318,9 +390,28 @@ const mergeOneLibrary = (context, sharedLib, ignore) => {
         }
       }
     } else if (!(key in context)) {
-      context[key] = copyWithNestedIgnores(sharedLib[key], skip, key)
+      // Any object bag, not only a plain one: a native-ESM module namespace
+      // (`import * as methods` outside a bundler) has a null prototype and
+      // fails isObject, yet lands here and becomes `context.methods` as is.
+      const bag = sharedLib[key]
+      const value = key === 'methods' && bag && typeof bag === 'object'
+        ? withoutProtectedMethods(bag, skip, refusedMethods)
+        : bag
+      context[key] = copyWithNestedIgnores(value, skip, key)
     }
   }
+  if (refusedMethods.length) warnRefusedBuiltinMethods(label, refusedMethods)
+}
+
+// A readable name for a library in the refusal warning: the wrapped entry's
+// identifier, else the library context's own key/name, else its position.
+const libraryLabel = (entry, lib, index) => {
+  if (entry !== lib) {
+    const ref = wrappedLibraryRef(entry)
+    if (isString(ref) && ref) return ref
+    if (entry.key || entry.name) return entry.key || entry.name
+  }
+  return (lib && (lib.key || lib.name)) || `sharedLibraries[${index}]`
 }
 
 /**
@@ -345,14 +436,15 @@ export const mergeSharedLibraries = (context, libraries) => {
   // consumer's own bags and the two can no longer be told apart.
   const ownDefaultFonts = defaultFontClaims(context.designSystem)
   for (let i = 0; i < libraries.length; i++) {
-    let sharedLib = libraries[i]
+    const entry = libraries[i]
+    let sharedLib = entry
     let ignore = EMPTY_IGNORE
     if (isWrappedLibrary(sharedLib)) {
       ignore = normalizeIgnoreList(sharedLib.ignoreList)
       sharedLib = sharedLib.library
     }
     if (!isObject(sharedLib)) continue
-    mergeOneLibrary(context, sharedLib, ignore)
+    mergeOneLibrary(context, sharedLib, ignore, libraryLabel(entry, sharedLib, i))
   }
   if (ownDefaultFonts.size) yieldLibraryDefaultFonts(context.designSystem, ownDefaultFonts)
 }

package/string.js

@@ -35,10 +35,53 @@ const getNestedValue = (obj, path) => {
   }, obj)
 }
 
+/**
+ * Is this exact string a template the AUTHOR wrote?
+ *
+ * FW-ELEMENT-TEMPLATES-RESOLVED-IN-RUNTIME-TEXT-FUNCTION-INJECTION-1.
+ * A `{{ key | fn }}` template invokes a project function, so resolving one
+ * inside a string that CAME FROM DATA turns content into code: a customer
+ * typing `{{ x | nkTheme }}` into a chat box flipped the theme, and
+ * `nkToast('info', 'literal test {{ demoShort | polyglot }} end')` rendered
+ * the translation. Every function on `context.functions` was reachable from
+ * user text, an AI reply or an API response.
+ *
+ * The contract: a template is an author-time literal. `create()` records
+ * every `{{ }}` string a definition declares (`__ref.__authoredTemplates`,
+ * see registerEffects), and only those strings resolve. A factory may
+ * FORWARD an authored template — the framework `Input` atom does exactly
+ * that with `attr.placeholder: el => el.placeholder` — but it may never
+ * introduce one. The parent chain counts, so a template declared on an
+ * ancestor and forwarded down still resolves; every entry in every set is a
+ * source literal, so no state-derived string is ever in one.
+ *
+ * `allowRuntimeTemplates: true` on an element is the explicit opt-out, for
+ * the rare surface that really does build templates at runtime. It re-opens
+ * function invocation from that element's content — never set it on an
+ * element that renders text a user or a model produced.
+ *
+ * This reads `this` by duck-typing (`__ref`, `parent`), exactly as the state
+ * and polyglot lookups below already do — `utils` never imports `element`.
+ * A caller with no `__ref` is not an element (a bare util call, a test) and
+ * keeps the old unconditional behaviour.
+ */
+const isAuthoredTemplate = (element, str) => {
+  if (!element || !element.__ref) return true
+  let el = element
+  while (el) {
+    if (el.allowRuntimeTemplates === true) return true
+    const authored = el.__ref && el.__ref.__authoredTemplates
+    if (authored && authored.has(str)) return true
+    el = el.parent
+  }
+  return false
+}
+
 export function replaceLiteralsWithObjectFields (str, state, options = {}) {
   const { bracketsLength = 2 } = options
   const bracketPattern = bracketsLength === 3 ? '{{{' : '{{'
   if (!str.includes(bracketPattern)) return str
+  if (!isAuthoredTemplate(this, str)) return str
 
   const reg = brackRegex[bracketsLength]
   const obj = state || this.state || {}