[Update] webcomponents, browser: callable cells, stricter hash path/flag semantics, and adopted stylesheets

This update introduces support for constructable/adopted stylesheets in modern browser environments, refines document style synchronization, and implements flexible proxy-based selectable/callable cells for browser.hash and browser.query.
The hash parsing logic now features refined path and flag semantics: top-level bare values without slashes parse into a path property and a companion boolean flag (e.g. #new parses to { path: "new", new: true }), whereas values with slashes parse into the path property only (e.g. #login/new parses to { path: "login/new" }). Top-level parenthesized groups are parsed directly as arrays. Browser.hash and Browser.query cells are now wrapped in a Proxy that can be called directly with a key/subpath argument to retrieve a selected child view, while preserving complete backward compatibility with all properties and methods of the underlying Cell instance.
On the WebComponent side, document styles are now synchronized and cloned into shadow roots using constructable stylesheets (via CSSStyleSheet.replaceSync) in supported environments, avoiding raw <style> element insertions where possible. Style node synchronization signature calculations have been hardened by introducing a 32-bit FNV-like text hashing mechanism (hashText) rather than relying purely on text lengths.
There are no breaking changes; all modified APIs and refactored helper relocations remain completely backward-compatible.
Changed:
- browser: Updated Browser.prototype.hash and Browser.prototype.query properties to return a callable proxy wrapper, enabling direct key selection via function calls (e.g., state.hash("key")) while retaining all original Cell APIs.
- browser: Updated parseHash(value) logic to support stricter path/flag semantics. A bare first segment sets a path property, setting a matching boolean flag unless it contains a slash /. Outermost parenthesized values parse directly as arrays.
- webcomponents: Clones and syncs document styles into WebComponent shadow roots using adopted constructable stylesheets (CSSStyleSheet) in supported browsers, falling back to style elements where needed.
- webcomponents: Enhanced getDocumentStylesSignature(doc) to compute a 32-bit hash (hashText) of style element text contents, ensuring high-fidelity change detection.
- utils: Relocated the def helper function from src/js/select/utils/func.js to src/js/select/utils/values.js. (Exports via the central utils.js compatibility barrel are unchanged and fully backward-compatible).
Added:
- browser: Added parse(value, fallback = {}) method to browser.hash for array-capable parsing and record sanitization.
- webcomponents: Added static options definition (webcomponent.options) to expose configuration defaults and exported webcomponent as default.
- tests: Added comprehensive test suite in tests/browser-parse.test.js covering hash-parsing, slash behavior, parenthesized group arrays, and edge cases.
- tests: Added adopted stylesheet and dynamic content mutation tests in tests/ui-webcomponent-children.test.js.
Removed:
- utils: Removed def helper from src/js/select/utils/func.js (re-added under utils/values.js).

Author: sebastien

docs/browser.md

@@ -72,6 +72,7 @@ Notes:
 - hash fragments may start with `#`
 - query parsing ignores any trailing `#fragment`
 - legacy `a=1&b=2` query syntax is not supported by default
+- hash parsing treats a bare first value as a `path` key; see [Browser Reference](ref-browser.md#hash) for details
 
 ## Error Handling
 

docs/ref-browser.md

@@ -96,6 +96,11 @@ Parsing rules:
 - special characters that force quoting include `&`, `,`, `(`, `)`, `=`, and `"`
 - any keyed entry inside `(...)` switches that group into object mode
 - bare items inside an object-mode group become boolean flags like `checked=T`
+- top-level parenthesized groups are parsed as arrays: `(a,b)` → `["a","b"]`
+- at the top level (outside parens), a bare first value (no `=`) becomes a `path` key:
+  - if the path value contains `/`, it sets `path` only (no boolean flag)
+  - without `/`, it also sets a boolean flag with the same name (`<value>: true`)
+- subsequent bare values after the first `,` become boolean flags
 
 Formatting rules:
 
@@ -116,6 +121,15 @@ hash.parse("#text=\"hello, world\",flag=T")
 hash.parse("(label=A,checked)")
 // => { label: "A", checked: true }
 
+hash.parse("#new,old")
+// => { path: "new", new: true, old: true }
+
+hash.parse("#login/new")
+// => { path: "login/new" }
+
+hash.parse("#(new,old)")
+// => ["new", "old"]
+
 hash.format({ z: 2, a: [1, 3], text: "hello, world" })
 // => "a=(1,3),text=\"hello, world\",z=2"
 

src/js/select/browser.js

@@ -240,6 +240,13 @@ class HashFormat extends RecordFormat {
 		super("browser.hash", serializer, warn);
 	}
 
+	parse(value, fallback = {}) {
+		const text = this.decodeText(value);
+		const parsed = this.safeParse(text, fallback);
+		if (Array.isArray(parsed)) return parsed;
+		return this.sanitizeRecord(parsed);
+	}
+
 	static DecodeComponent(value) {
 		if (!value?.includes("%")) return value;
 		try {
@@ -576,6 +583,48 @@ function formatRecord(value) {
 function parseHash(value) {
 	const source = `${value || ""}`.replace(/^#/, "");
 	if (!source) return {};
+	if (source.startsWith("(")) {
+		const parsed = HashFormat.ParseHash(source);
+		return normalizeHashValue(parsed);
+	}
+	const [sepIdx, sep] = HashFormat.NextSeparator(source, 0);
+	const firstSegment = sepIdx === null ? source : source.substring(0, sepIdx).trim();
+	if (firstSegment && sep !== "=") {
+		const pathValue = HashFormat.ParseAtom(firstSegment);
+		const pathStr = `${pathValue}`;
+		if (sep !== ",") {
+			return pathStr.includes("/")
+				? { path: pathValue }
+				: { path: pathValue, [pathStr]: true };
+		}
+		const remaining = source.substring(sepIdx + 1).trim();
+		if (!remaining) {
+			return pathStr.includes("/")
+				? { path: pathValue }
+				: { path: pathValue, [pathStr]: true };
+		}
+		const rest = normalizeHashValue(HashFormat.ParseHash(remaining));
+		if (Array.isArray(rest)) {
+			const result = { path: pathValue };
+			if (!pathStr.includes("/")) result[pathStr] = true;
+			for (let i = 0; i < rest.length; i++) result[rest[i]] = true;
+			return result;
+		}
+		if (typeof rest === "string") {
+			const result = { path: pathValue };
+			if (!pathStr.includes("/")) result[pathStr] = true;
+			result[rest] = true;
+			return result;
+		}
+		if (isObject(rest)) {
+			rest.path = pathValue;
+			if (!pathStr.includes("/")) rest[pathStr] = true;
+			return rest;
+		}
+		return pathStr.includes("/")
+			? { path: pathValue }
+			: { path: pathValue, [pathStr]: true };
+	}
 	const parsed = HashFormat.ParseHash(source);
 	return normalizeHashValue(parsed);
 }
@@ -764,7 +813,7 @@ class LocationState {
 			{
 				mode: this.mode,
 				merge: true,
-				normalize: (value) => this.hashFormat.sanitizeRecord(value),
+				normalize: (value) => Array.isArray(value) ? value : this.hashFormat.sanitizeRecord(value),
 				writer: (_value, settings) => this.writeURL(settings.mode),
 			},
 		);
@@ -879,9 +928,37 @@ function looksLikeHashText(value) {
 	return value.startsWith("(") && value.endsWith(")")
 }
 
+// Function: selectable
+// Wraps a cell into a callable function that doubles as a key-based selector.
+// When called with no arguments, returns the underlying cell.
+// When called with a key (and optional subpath), returns `cell.select(...)`.
+// All property access and methods are forwarded to the cell via Proxy.
+function selectable(cell) {
+	const fn = (key, path) => {
+		if (key === undefined || key === null) return cell
+		const keyPath = Array.isArray(key) ? key : [key]
+		if (path === undefined) return cell.select(keyPath)
+		const extraPath = Array.isArray(path) ? path : `${path}`.split(".")
+		return cell.select([...keyPath, ...extraPath])
+	}
+	return new Proxy(fn, {
+		get(_, p) {
+			if (p in fn) return fn[p]
+			const v = Reflect.get(cell, p)
+			return typeof v === "function" ? v.bind(cell) : v
+		},
+		set(_, p, v) { return Reflect.set(cell, p, v) },
+		has(_, p) { return p in fn || p in cell },
+	})
+}
+
 // Class: Browser
 // Browser-backed state manager for URL, hash, query, and local storage.
 //
+// `hash` and `query` are callable selectors: `state.hash("key")` returns a
+// `Selected` view at that key within the hash value. Call with no args to get
+// the underlying cell. `state.path` is a plain cell.
+//
 // Attributes:
 // - `location`: LocationState - shared URL state wrapper
 // - `win`: Window? - browser window used for side effects
@@ -891,8 +968,8 @@ function looksLikeHashText(value) {
 // - `locals`: Map - registered local storage cells
 // - `internals`: Map - internal named cells
 // - `path`: Cell - path state cell
-// - `query`: Cell - query state cell
-// - `hash`: Cell - hash state cell
+// - `query`: Cell (callable) - query state cell
+// - `hash`: Cell (callable) - hash state cell
 class Browser {
 	constructor(options = {}) {
 		this.location = new LocationState(options);
@@ -908,8 +985,8 @@ class Browser {
 		this.locals = new Map();
 		this.internals = new Map();
 		this.path = this.location.path;
-		this.query = this.location.query;
-		this.hash = this.location.hash;
+		this.query = selectable(this.location.query);
+		this.hash = selectable(this.location.hash);
 
 		this.local = this.local.bind(this);
 		this.internal = this.internal.bind(this);

src/js/select/ui/webcomponents.js

@@ -18,7 +18,7 @@
 // ----------------------------------------------------------------------------
 
 import { toCamelCase, toKebabCase } from "../formats.js";
-import { asText, isObject, Nothing } from "../utils.js";
+import { asText, def, isObject, Nothing } from "../utils.js";
 import { getUIInstance } from "./components/instance.js";
 import { log } from "./templates.js";
 
@@ -33,13 +33,20 @@ const BaseHTMLElement = globalThis.HTMLElement || class {};
 const documentStyleSheetCache = new WeakMap();
 const documentStyleSubscribers = new WeakMap();
 const documentStyleObservers = new WeakMap();
+const OPTIONS = {
+	shadow: true, // Shadow DOM by default
+	mode: "open", // Open Shadow DOM by default
+};
 
 function isStyleSheetNode(node) {
 	if (!node || node.nodeType !== Node.ELEMENT_NODE) {
 		return false;
 	}
 	const tagName = node.tagName?.toLowerCase();
-	return tagName === "style" || (tagName === "link" && node.relList?.contains("stylesheet"));
+	return (
+		tagName === "style" ||
+		(tagName === "link" && node.relList?.contains("stylesheet"))
+	);
 }
 
 function isStyleSheetMutation(mutation) {
@@ -59,6 +66,14 @@ function isStyleSheetMutation(mutation) {
 	return false;
 }
 
+function hashText(value) {
+	let hash = 0;
+	for (let i = 0; i < value.length; i++) {
+		hash = (hash * 31 + value.charCodeAt(i)) | 0;
+	}
+	return hash;
+}
+
 function getDocumentStylesSignature(doc) {
 	if (!doc?.head?.querySelectorAll) {
 		return "";
@@ -68,7 +83,10 @@ function getDocumentStylesSignature(doc) {
 	for (let i = 0; i < nodes.length; i++) {
 		const node = nodes[i];
 		if (node.tagName?.toLowerCase() === "style") {
-			signature.push(`style:${node.id || ""}:${node.media || ""}:${node.textContent?.length || 0}`);
+			const text = node.textContent || "";
+			signature.push(
+				`style:${node.id || ""}:${node.media || ""}:${text.length}:${hashText(text)}`,
+			);
 		} else {
 			signature.push(
 				`link:${node.getAttribute("href") || ""}:${node.getAttribute("media") || ""}:${node.hasAttribute("disabled")}`,
@@ -257,11 +275,34 @@ function buildDocumentStyleSheets(doc) {
 		return { sheets: [], fallbackNodes: [] };
 	}
 	const nodes = doc.head.querySelectorAll("style,link[rel~='stylesheet']");
+	const sheets = [];
 	const fallbackNodes = [];
+	const HTMLStyleElementType =
+		globalThis.HTMLStyleElement || doc.defaultView?.HTMLStyleElement;
+	const CSSStyleSheetType =
+		globalThis.CSSStyleSheet || doc.defaultView?.CSSStyleSheet;
 	for (let i = 0; i < nodes.length; i++) {
-		fallbackNodes.push(nodes[i]);
+		const node = nodes[i];
+		if (
+			HTMLStyleElementType &&
+			node instanceof HTMLStyleElementType &&
+			typeof CSSStyleSheetType === "function"
+		) {
+			try {
+				const sheet = new CSSStyleSheetType();
+				sheet.replaceSync(node.textContent || "");
+				sheets.push(sheet);
+				continue;
+			} catch (error) {
+				log.warn("UIWebComponent: could not adopt document style, details", {
+					node,
+					error,
+				});
+			}
+		}
+		fallbackNodes.push(node);
 	}
-	return { sheets: [], fallbackNodes };
+	return { sheets, fallbackNodes };
 }
 
 function getDocumentStyles(doc) {
@@ -280,10 +321,10 @@ function getDocumentStyles(doc) {
 
 function cloneDocumentStyles(root, options) {
 	if (options?.documentStyles === false) {
-		return { sheets: [], fallbackNodes: [], headChildCount: 0 };
+		return { sheets: [], fallbackNodes: [], signature: "" };
 	}
 	if (!root || root === document || !document?.head?.querySelectorAll) {
-		return { sheets: [], fallbackNodes: [], headChildCount: 0 };
+		return { sheets: [], fallbackNodes: [], signature: "" };
 	}
 	return getDocumentStyles(document);
 }
@@ -314,8 +355,8 @@ class UIWebComponent extends BaseHTMLElement {
 		options = {},
 	) {
 		super();
-		const useShadow = options.shadow !== false;
-		const shadowMode = options.shadowMode || "open";
+		const useShadow = def(options.shadow, OPTIONS.shadow) !== false;
+		const shadowMode = def(options.mode, OPTIONS.mode) || "open";
 		this.root =
 			useShadow && typeof this.attachShadow === "function"
 				? this.shadowRoot || this.attachShadow({ mode: shadowMode })
@@ -498,11 +539,14 @@ class UIWebComponent extends BaseHTMLElement {
 		}
 		const parent = getUIInstance(parentId);
 		if (!parent) {
-			log.warn("UIWebComponent: ui-parent did not resolve to a mounted instance", {
-				attribute: UI_PARENT_ATTRIBUTE,
-				parentId,
-				host: this,
-			});
+			log.warn(
+				"UIWebComponent: ui-parent did not resolve to a mounted instance",
+				{
+					attribute: UI_PARENT_ATTRIBUTE,
+					parentId,
+					host: this,
+				},
+			);
 		}
 		return parent;
 	}
@@ -705,7 +749,9 @@ function webcomponent(
 	registry.define(name, WebComponent);
 	return WebComponent;
 }
+webcomponent.options = OPTIONS;
 
 export { Adopted, Disconnect, UIWebComponent, webcomponent };
+export default webcomponent;
 
 // EOF

src/js/select/utils/func.js

@@ -14,17 +14,6 @@ import { access, bool, isObject, isThenable, isAnnotable } from "./values.js";
 // BASIC HELPERS
 //
 // ----------------------------------------------------------------------------
-
-// Function: def
-// Returns the first argument that is not `undefined`.
-function def(...rest) {
-	for (const v of rest) {
-		if (v !== undefined) {
-			return v;
-		}
-	}
-}
-
 // Function: swallow
 // Returns the last argument in `args`.
 function swallow(...args) {
@@ -132,7 +121,9 @@ function collect(value, asObject = false) {
 							resolved,
 						]);
 					}
-					return Promise.all(pending).then((resolved) => collect(resolved, true));
+					return Promise.all(pending).then((resolved) =>
+						collect(resolved, true),
+					);
 				}
 			}
 			const res = {};
@@ -261,7 +252,6 @@ function memo(guards, functor) {
 export {
 	ary,
 	asTrue,
-	def,
 	extractor,
 	idem,
 	meta,

src/js/select/utils/values.js

@@ -14,6 +14,16 @@
 //
 // ----------------------------------------------------------------------------
 
+// Function: def
+// Returns the first argument that is not `undefined`.
+function def(...rest) {
+	for (const v of rest) {
+		if (v !== undefined) {
+			return v;
+		}
+	}
+}
+
 // Function: isObject
 // Returns true when `value` is a plain object.
 function isObject(value) {
@@ -510,6 +520,7 @@ export {
 	bool,
 	clone,
 	composite,
+	def,
 	dict,
 	empty,
 	expand,