@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/_chunks/href-validation-BIrxavIy.js

@@ -0,0 +1,213 @@
+//#region src/shared/slot-params.ts
+/**
+* The params a slot sees: the main route's as a base, the slot's own on top.
+*
+* Params from segments *above* the slot are not re-derived by the slot's own
+* chain, so they have to come from the main route; params the slot does
+* re-derive may have a different type than the main route gave them, so the
+* slot's win.
+*
+* Null-prototype, like every other param record the framework hands out
+* (`coerceSegmentParams` installs one unconditionally). A spread literal would
+* inherit `Object.prototype`, so a lookup for a param the route does not
+* define would resolve to an inherited member — `params.constructor` returning
+* a function instead of `undefined` — in the one param record that was built
+* by merging. See design/13-security.md #36c.
+*/
+function mergeSlotParams(mainParams, slotParams) {
+	return Object.assign(Object.create(null), mainParams, slotParams);
+}
+/**
+* Resolve the params for a segment path against a published slot map.
+*
+* Returns the merge when `segmentPath` names a slot that published params,
+* and the main route's record otherwise — an ordinary (non-slot) segment
+* path, an unknown path, or a request with no slots at all. Mirrors the
+* server's `getSegmentParams(segmentPath)` branch exactly.
+*
+* `Object.hasOwn` rather than `in` or a truthiness test: the map arrives from
+* JSON, so a segment path of `constructor` or `toString` would otherwise
+* resolve to an inherited member of `Object.prototype`.
+*/
+function resolveSegmentParams(mainParams, slotParams, segmentPath) {
+	if (!segmentPath || !slotParams || !Object.hasOwn(slotParams, segmentPath)) return mainParams;
+	return cachedMerge(mainParams, slotParams, segmentPath);
+}
+/**
+* The merged record for one (main record, slot map, path) triple, reused until
+* one of the three changes.
+*
+* `useSegmentParams(slotPath)` calls this on every render. Returning a fresh
+* object each time makes the hook's result change by reference on renders where
+* nothing navigated, so a component using it as a `useEffect` dependency
+* re-runs the effect — and re-renders in a loop if that effect sets state —
+* while memoized children below it lose their memoization.
+*
+* Keyed on the *identities* of the two records, not their contents: both are
+* replaced rather than mutated on every navigation (`ParamsProvider`'s memoized
+* value and the server's per-request store), so identity is the correct
+* equality here and a deep comparison would be slower and no more accurate.
+*
+* A `WeakMap` chain rather than a `Map`, so a superseded navigation's records
+* and their merges become collectable as soon as nothing else holds them.
+*/
+var mergeCache = /* @__PURE__ */ new WeakMap();
+function cachedMerge(mainParams, slotParams, segmentPath) {
+	let bySlotMap = mergeCache.get(mainParams);
+	if (!bySlotMap) {
+		bySlotMap = /* @__PURE__ */ new WeakMap();
+		mergeCache.set(mainParams, bySlotMap);
+	}
+	let byPath = bySlotMap.get(slotParams);
+	if (!byPath) {
+		byPath = /* @__PURE__ */ new Map();
+		bySlotMap.set(slotParams, byPath);
+	}
+	const cached = byPath.get(segmentPath);
+	if (cached) return cached;
+	const merged = mergeSlotParams(mainParams, slotParams[segmentPath]);
+	byPath.set(segmentPath, merged);
+	return merged;
+}
+//#endregion
+//#region src/shared/merge-search-params.ts
+/**
+* Shared utility for merging preserved search params into a target URL.
+*
+* Used by both <Link> (client) and redirect() (server). Extracted to a shared
+* module to avoid importing client code ('use client') from server modules.
+*/
+/**
+* Merge preserved search params from the current URL into a target href.
+*
+* When `preserve` is `true`, all current search params are merged.
+* When `preserve` is a `string[]`, only the named params are merged.
+*
+* The target href's own search params take precedence — preserved params
+* are only added if the target doesn't already define them.
+*
+* @param targetHref - The resolved target href (may already contain query string)
+* @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+* @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+* @returns The target href with preserved search params merged in
+*/
+function mergePreservedSearchParams(targetHref, currentSearch, preserve) {
+	const currentParams = new URLSearchParams(currentSearch);
+	if (currentParams.size === 0) return targetHref;
+	const hashIdx = targetHref.indexOf("#");
+	const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+	const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : "";
+	const qIdx = hrefWithoutHash.indexOf("?");
+	const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+	const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : "");
+	const merged = new URLSearchParams(targetParams);
+	for (const [key, value] of currentParams) if (!targetParams.has(key)) {
+		if (preserve === true || preserve.includes(key)) merged.append(key, value);
+	}
+	const qs = merged.toString();
+	return (qs ? `${targetPath}?${qs}` : targetPath) + hash;
+}
+//#endregion
+//#region src/shared/href-validation.ts
+/**
+* Shared href/URL validation for all navigation sinks.
+*
+* Used by <Link>, useRouter().push/replace, and redirectExternal().
+* Single source of truth for dangerous-scheme detection — prevents
+* control-character smuggling that bypasses naive regex checks.
+*
+* See design/13-security.md §"Link scheme injection" (test #9)
+* and design/07-routing.md §"<Link> Scheme Validation".
+*/
+/**
+* All C0 control characters (U+0000–U+001F) that browsers strip during
+* URL preprocessing. Browsers and `new URL()` strip the full C0 range,
+* not just tab/LF/CR — so we must match that behavior to prevent
+* bypass vectors like `\x00javascript:alert(1)`.
+*/
+var CONTROL_CHARS_RE = /[\x00-\x1f]/g;
+var DANGEROUS_SCHEMES = /* @__PURE__ */ new Set([
+	"javascript:",
+	"data:",
+	"vbscript:"
+]);
+/**
+* Strip C0 control chars and leading whitespace, then extract the scheme.
+* Returns the lowercase scheme (e.g. "javascript:") or null if no scheme.
+*/
+function extractScheme(href) {
+	const cleaned = href.replace(CONTROL_CHARS_RE, "").trimStart();
+	const match = /^([a-z][a-z0-9+.-]*:)/i.exec(cleaned);
+	return match ? match[1].toLowerCase() : null;
+}
+/**
+* Validate an href for navigation sinks (<Link>, useRouter, etc.).
+*
+* Rejects dangerous schemes (javascript:, data:, vbscript:) even when
+* control characters are embedded to bypass naive regex checks.
+* Also rejects protocol-relative URLs (//evil.com).
+*
+* Throws on rejection. Safe hrefs pass through silently.
+*/
+function validateNavigationHref(href) {
+	if (href.replace(CONTROL_CHARS_RE, "").trimStart().replaceAll("\\", "/").startsWith("//")) throw new Error(`Navigation received a protocol-relative or backslash-prefixed URL: "${href}". Use an absolute URL with an explicit scheme or a relative path.`);
+	const scheme = extractScheme(href);
+	if (scheme && DANGEROUS_SCHEMES.has(scheme)) throw new Error(`Navigation received a dangerous href: "${href}". javascript:, data:, and vbscript: URLs are not allowed.`);
+}
+/**
+* Check if an href is internal (same-origin navigation) or external.
+*
+* Strips control characters before checking so that "java\tscript:" is
+* correctly identified as having a scheme (and thus not internal).
+*/
+function isInternalHref(href) {
+	const cleaned = href.replace(CONTROL_CHARS_RE, "").trimStart().replaceAll("\\", "/");
+	if (cleaned.startsWith("//")) return false;
+	if (cleaned.startsWith("/") || cleaned.startsWith("#") || cleaned.startsWith("?")) return true;
+	if (extractScheme(href)) return false;
+	return true;
+}
+/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */
+var ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+/**
+* Assert that a redirect target is a relative path — rejects absolute and
+* protocol-relative URLs. Used by both the server `redirect()` primitive and
+* the client next/navigation shim so they enforce identical semantics.
+*
+* Normalizes for validation only: strips C0 controls, trims, then replaces
+* backslashes with forward slashes. Browsers normalize \ → / during URL
+* resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+* redirect). See design/13-security.md tests #8, #8a–#8c.
+*/
+function assertRelativeRedirectPath(path) {
+	const cleaned = path.replace(CONTROL_CHARS_RE, "").trimStart().replaceAll("\\", "/");
+	if (ABSOLUTE_URL_RE.test(cleaned)) throw new Error(`redirect() only accepts relative URLs. Got absolute URL: "${path}". Use redirectExternal(url, allowList) for external redirects.`);
+	if (/[\x00-\x1f]/.test(path)) throw new Error("redirect() received a path containing control characters (U+0000–U+001F). Sanitize user input before passing it to redirect().");
+}
+var SAFE_REDIRECT_SCHEMES = /* @__PURE__ */ new Set(["http:", "https:"]);
+/**
+* Validate and canonicalize an external redirect URL.
+*
+* Requires http: or https: scheme and checks origin against an allow-list.
+* Returns the parsed canonical URL string (from URL.href) to prevent
+* raw user input from reaching the Location header.
+*
+* @throws On invalid URL, dangerous scheme, or origin not in allow-list.
+*/
+function validateExternalRedirectUrl(url, allowList) {
+	const cleaned = url.replace(CONTROL_CHARS_RE, "").trimStart();
+	if (cleaned.startsWith("//")) throw new Error(`redirectExternal() received a protocol-relative URL: "${url}". Use an absolute URL with http: or https: scheme.`);
+	let parsed;
+	try {
+		parsed = new URL(cleaned);
+	} catch {
+		throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
+	}
+	if (!SAFE_REDIRECT_SCHEMES.has(parsed.protocol)) throw new Error(`redirectExternal() received a non-http(s) URL: "${url}". Only http: and https: schemes are allowed for external redirects.`);
+	if (!allowList.includes(parsed.origin)) throw new Error(`redirectExternal() target "${parsed.origin}" is not in the allow-list. Allowed: [${allowList.join(", ")}]`);
+	return parsed.href;
+}
+//#endregion
+export { mergePreservedSearchParams as a, validateNavigationHref as i, isInternalHref as n, resolveSegmentParams as o, validateExternalRedirectUrl as r, assertRelativeRedirectPath as t };
+
+//# sourceMappingURL=href-validation-BIrxavIy.js.map

package/dist/_chunks/href-validation-BIrxavIy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"href-validation-BIrxavIy.js","names":[],"sources":["../../src/shared/slot-params.ts","../../src/shared/merge-search-params.ts","../../src/shared/href-validation.ts"],"sourcesContent":["/**\n * Per-slot segment params — the one definition both halves of the API read.\n *\n * A parallel slot matches the URL through its *own* sub-tree, so it can derive\n * a param the main route never had, or derive the same name with a different\n * type (`[...year]` → `string[]` where the main route's `[year]` gave\n * `string`). The server answers `getSegmentParams(slotPath)` from a per-slot\n * map; the client answers `useSegmentParams(slotPath)` from the same map,\n * published on the RSC payload (TIM-1285).\n *\n * The merge lives here rather than in either half because the two must agree\n * about what \"the slot's params\" are — a divergence is invisible until\n * somebody reads a param of the wrong type, which is exactly the class of bug\n * this module closes.\n *\n * Isomorphic: no server or client imports.\n *\n * See design/41-global-params.md §\"Params in a parallel slot\".\n */\n\nimport type { CoercedParams } from './param-value.ts';\n\n/** Slot tree path → that slot's own coerced params. */\nexport type SlotParamsRecord = Record<string, CoercedParams>;\n\n/**\n * The params a slot sees: the main route's as a base, the slot's own on top.\n *\n * Params from segments *above* the slot are not re-derived by the slot's own\n * chain, so they have to come from the main route; params the slot does\n * re-derive may have a different type than the main route gave them, so the\n * slot's win.\n *\n * Null-prototype, like every other param record the framework hands out\n * (`coerceSegmentParams` installs one unconditionally). A spread literal would\n * inherit `Object.prototype`, so a lookup for a param the route does not\n * define would resolve to an inherited member — `params.constructor` returning\n * a function instead of `undefined` — in the one param record that was built\n * by merging. See design/13-security.md #36c.\n */\nexport function mergeSlotParams(\n  mainParams: CoercedParams,\n  slotParams: CoercedParams\n): CoercedParams {\n  return Object.assign(Object.create(null), mainParams, slotParams);\n}\n\n/**\n * Resolve the params for a segment path against a published slot map.\n *\n * Returns the merge when `segmentPath` names a slot that published params,\n * and the main route's record otherwise — an ordinary (non-slot) segment\n * path, an unknown path, or a request with no slots at all. Mirrors the\n * server's `getSegmentParams(segmentPath)` branch exactly.\n *\n * `Object.hasOwn` rather than `in` or a truthiness test: the map arrives from\n * JSON, so a segment path of `constructor` or `toString` would otherwise\n * resolve to an inherited member of `Object.prototype`.\n */\nexport function resolveSegmentParams(\n  mainParams: CoercedParams,\n  slotParams: SlotParamsRecord | null | undefined,\n  segmentPath: string | undefined\n): CoercedParams {\n  if (!segmentPath || !slotParams || !Object.hasOwn(slotParams, segmentPath)) return mainParams;\n  return cachedMerge(mainParams, slotParams, segmentPath);\n}\n\n/**\n * The merged record for one (main record, slot map, path) triple, reused until\n * one of the three changes.\n *\n * `useSegmentParams(slotPath)` calls this on every render. Returning a fresh\n * object each time makes the hook's result change by reference on renders where\n * nothing navigated, so a component using it as a `useEffect` dependency\n * re-runs the effect — and re-renders in a loop if that effect sets state —\n * while memoized children below it lose their memoization.\n *\n * Keyed on the *identities* of the two records, not their contents: both are\n * replaced rather than mutated on every navigation (`ParamsProvider`'s memoized\n * value and the server's per-request store), so identity is the correct\n * equality here and a deep comparison would be slower and no more accurate.\n *\n * A `WeakMap` chain rather than a `Map`, so a superseded navigation's records\n * and their merges become collectable as soon as nothing else holds them.\n */\nconst mergeCache = new WeakMap<object, WeakMap<object, Map<string, CoercedParams>>>();\n\nfunction cachedMerge(\n  mainParams: CoercedParams,\n  slotParams: SlotParamsRecord,\n  segmentPath: string\n): CoercedParams {\n  let bySlotMap = mergeCache.get(mainParams);\n  if (!bySlotMap) {\n    bySlotMap = new WeakMap();\n    mergeCache.set(mainParams, bySlotMap);\n  }\n  let byPath = bySlotMap.get(slotParams);\n  if (!byPath) {\n    byPath = new Map();\n    bySlotMap.set(slotParams, byPath);\n  }\n  const cached = byPath.get(segmentPath);\n  if (cached) return cached;\n  const merged = mergeSlotParams(mainParams, slotParams[segmentPath]);\n  byPath.set(segmentPath, merged);\n  return merged;\n}\n","/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split hash fragment from target before processing query params.\n  // Hash must come after query string: /path?query=value#hash\n  const hashIdx = targetHref.indexOf('#');\n  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;\n  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';\n\n  // Split target into path and existing query\n  const qIdx = hrefWithoutHash.indexOf('?');\n  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;\n  return pathWithQuery + hash;\n}\n","/**\n * Shared href/URL validation for all navigation sinks.\n *\n * Used by <Link>, useRouter().push/replace, and redirectExternal().\n * Single source of truth for dangerous-scheme detection — prevents\n * control-character smuggling that bypasses naive regex checks.\n *\n * See design/13-security.md §\"Link scheme injection\" (test #9)\n * and design/07-routing.md §\"<Link> Scheme Validation\".\n */\n\n/**\n * All C0 control characters (U+0000–U+001F) that browsers strip during\n * URL preprocessing. Browsers and `new URL()` strip the full C0 range,\n * not just tab/LF/CR — so we must match that behavior to prevent\n * bypass vectors like `\\x00javascript:alert(1)`.\n */\n// eslint-disable-next-line no-control-regex -- intentional: must match all C0 controls to prevent bypass\nconst CONTROL_CHARS_RE = /[\\x00-\\x1f]/g;\n\nconst DANGEROUS_SCHEMES = new Set(['javascript:', 'data:', 'vbscript:']);\n\n/**\n * Strip C0 control chars and leading whitespace, then extract the scheme.\n * Returns the lowercase scheme (e.g. \"javascript:\") or null if no scheme.\n */\nfunction extractScheme(href: string): string | null {\n  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart();\n  const match = /^([a-z][a-z0-9+.-]*:)/i.exec(cleaned);\n  return match ? match[1].toLowerCase() : null;\n}\n\n/**\n * Validate an href for navigation sinks (<Link>, useRouter, etc.).\n *\n * Rejects dangerous schemes (javascript:, data:, vbscript:) even when\n * control characters are embedded to bypass naive regex checks.\n * Also rejects protocol-relative URLs (//evil.com).\n *\n * Throws on rejection. Safe hrefs pass through silently.\n */\nexport function validateNavigationHref(href: string): void {\n  // Normalize for validation: strip C0 controls, trim, then replace backslashes\n  // with forward slashes. Browsers normalize \\ → / during URL resolution, so\n  // \"/\\evil.com\" becomes \"//evil.com\" (protocol-relative open redirect).\n  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\\\', '/');\n\n  // Protocol-relative URLs can redirect to attacker-controlled origins\n  if (cleaned.startsWith('//')) {\n    throw new Error(\n      `Navigation received a protocol-relative or backslash-prefixed URL: \"${href}\". ` +\n        'Use an absolute URL with an explicit scheme or a relative path.'\n    );\n  }\n\n  const scheme = extractScheme(href);\n  if (scheme && DANGEROUS_SCHEMES.has(scheme)) {\n    throw new Error(\n      `Navigation received a dangerous href: \"${href}\". ` +\n        'javascript:, data:, and vbscript: URLs are not allowed.'\n    );\n  }\n}\n\n/**\n * Check if an href is internal (same-origin navigation) or external.\n *\n * Strips control characters before checking so that \"java\\tscript:\" is\n * correctly identified as having a scheme (and thus not internal).\n */\nexport function isInternalHref(href: string): boolean {\n  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\\\', '/');\n\n  if (cleaned.startsWith('//')) return false;\n  if (cleaned.startsWith('/') || cleaned.startsWith('#') || cleaned.startsWith('?')) return true;\n\n  const scheme = extractScheme(href);\n  if (scheme) return false;\n\n  return true;\n}\n\n/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */\nconst ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\\d+\\-.]*:|\\/\\/)/;\n\n/**\n * Assert that a redirect target is a relative path — rejects absolute and\n * protocol-relative URLs. Used by both the server `redirect()` primitive and\n * the client next/navigation shim so they enforce identical semantics.\n *\n * Normalizes for validation only: strips C0 controls, trims, then replaces\n * backslashes with forward slashes. Browsers normalize \\ → / during URL\n * resolution, so \"/\\evil.com\" becomes \"//evil.com\" (protocol-relative open\n * redirect). See design/13-security.md tests #8, #8a–#8c.\n */\nexport function assertRelativeRedirectPath(path: string): void {\n  const cleaned = path.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\\\', '/');\n\n  if (ABSOLUTE_URL_RE.test(cleaned)) {\n    throw new Error(\n      `redirect() only accepts relative URLs. Got absolute URL: \"${path}\". ` +\n        'Use redirectExternal(url, allowList) for external redirects.'\n    );\n  }\n\n  // eslint-disable-next-line no-control-regex -- intentional: must match C0 controls\n  if (/[\\x00-\\x1f]/.test(path)) {\n    throw new Error(\n      `redirect() received a path containing control characters (U+0000–U+001F). ` +\n        'Sanitize user input before passing it to redirect().'\n    );\n  }\n}\n\nconst SAFE_REDIRECT_SCHEMES = new Set(['http:', 'https:']);\n\n/**\n * Validate and canonicalize an external redirect URL.\n *\n * Requires http: or https: scheme and checks origin against an allow-list.\n * Returns the parsed canonical URL string (from URL.href) to prevent\n * raw user input from reaching the Location header.\n *\n * @throws On invalid URL, dangerous scheme, or origin not in allow-list.\n */\nexport function validateExternalRedirectUrl(url: string, allowList: string[]): string {\n  // Strip control chars before parsing to prevent scheme smuggling\n  const cleaned = url.replace(CONTROL_CHARS_RE, '').trimStart();\n\n  if (cleaned.startsWith('//')) {\n    throw new Error(\n      `redirectExternal() received a protocol-relative URL: \"${url}\". ` +\n        'Use an absolute URL with http: or https: scheme.'\n    );\n  }\n\n  let parsed: URL;\n  try {\n    parsed = new URL(cleaned);\n  } catch {\n    throw new Error(`redirectExternal() received an invalid URL: \"${url}\"`);\n  }\n\n  if (!SAFE_REDIRECT_SCHEMES.has(parsed.protocol)) {\n    throw new Error(\n      `redirectExternal() received a non-http(s) URL: \"${url}\". ` +\n        'Only http: and https: schemes are allowed for external redirects.'\n    );\n  }\n\n  if (!allowList.includes(parsed.origin)) {\n    throw new Error(\n      `redirectExternal() target \"${parsed.origin}\" is not in the allow-list. ` +\n        `Allowed: [${allowList.join(', ')}]`\n    );\n  }\n\n  return parsed.href;\n}\n"],"mappings":"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"}

package/dist/_chunks/json-lossy-check-ClNvBM_3.js

@@ -0,0 +1,63 @@
+//#region src/cache/json-lossy-check.ts
+var LOSSY_TYPES = [
+	"Date",
+	"Map",
+	"Set",
+	"BigInt"
+];
+var hasWarned = false;
+/**
+* Dev-mode warning when a cache value contains types that lose fidelity
+* through JSON round-trip. Only runs in development — no-op in production.
+*
+* Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).
+* Emits once per process to avoid log spam.
+*/
+function warnLossyJsonValue(value, cacheKey) {
+	if (hasWarned) return;
+	if (process.env.NODE_ENV === "production") return;
+	const lossy = findLossyTypes(value, /* @__PURE__ */ new Set(), 0);
+	if (lossy.size === 0) return;
+	hasWarned = true;
+	const types = [...lossy].join(", ");
+	console.warn(`[timber] cache value for key "${cacheKey}" contains ${types} — these types lose fidelity through JSON serialization in Redis/KV cache handlers. Date becomes an ISO string, Map/Set become {}, BigInt throws. The MemoryCacheHandler preserves them. Consider transforming values to JSON-safe types before caching, or use MemoryCacheHandler for values that require type preservation.`);
+}
+function findLossyTypes(value, seen, depth) {
+	const lossy = /* @__PURE__ */ new Set();
+	if (depth > 8 || value === null || value === void 0) return lossy;
+	if (typeof value === "bigint") {
+		lossy.add("BigInt");
+		return lossy;
+	}
+	if (typeof value !== "object" && typeof value !== "function") return lossy;
+	if (seen.has(value)) return lossy;
+	seen.add(value);
+	if (value instanceof Date) {
+		lossy.add("Date");
+		return lossy;
+	}
+	if (value instanceof Map) {
+		lossy.add("Map");
+		return lossy;
+	}
+	if (value instanceof Set) {
+		lossy.add("Set");
+		return lossy;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			for (const t of findLossyTypes(item, seen, depth + 1)) lossy.add(t);
+			if (lossy.size === LOSSY_TYPES.length) return lossy;
+		}
+		return lossy;
+	}
+	for (const k of Object.keys(value)) {
+		for (const t of findLossyTypes(value[k], seen, depth + 1)) lossy.add(t);
+		if (lossy.size === LOSSY_TYPES.length) return lossy;
+	}
+	return lossy;
+}
+//#endregion
+export { warnLossyJsonValue as t };
+
+//# sourceMappingURL=json-lossy-check-ClNvBM_3.js.map

package/dist/_chunks/json-lossy-check-ClNvBM_3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-lossy-check-ClNvBM_3.js","names":[],"sources":["../../src/cache/json-lossy-check.ts"],"sourcesContent":["const LOSSY_TYPES = ['Date', 'Map', 'Set', 'BigInt'] as const;\n\nlet hasWarned = false;\n\n/**\n * Dev-mode warning when a cache value contains types that lose fidelity\n * through JSON round-trip. Only runs in development — no-op in production.\n *\n * Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).\n * Emits once per process to avoid log spam.\n */\nexport function warnLossyJsonValue(value: unknown, cacheKey: string): void {\n  if (hasWarned) return;\n  if (process.env.NODE_ENV === 'production') return;\n\n  const lossy = findLossyTypes(value, new Set(), 0);\n  if (lossy.size === 0) return;\n\n  hasWarned = true;\n  const types = [...lossy].join(', ');\n  console.warn(\n    `[timber] cache value for key \"${cacheKey}\" contains ${types} — ` +\n      'these types lose fidelity through JSON serialization in Redis/KV cache handlers. ' +\n      'Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +\n      'The MemoryCacheHandler preserves them. Consider transforming values ' +\n      'to JSON-safe types before caching, or use MemoryCacheHandler for ' +\n      'values that require type preservation.'\n  );\n}\n\nfunction findLossyTypes(value: unknown, seen: Set<unknown>, depth: number): Set<string> {\n  const lossy = new Set<string>();\n  if (depth > 8 || value === null || value === undefined) return lossy;\n  if (typeof value === 'bigint') {\n    lossy.add('BigInt');\n    return lossy;\n  }\n  if (typeof value !== 'object' && typeof value !== 'function') return lossy;\n  if (seen.has(value)) return lossy;\n  seen.add(value);\n\n  if (value instanceof Date) {\n    lossy.add('Date');\n    return lossy;\n  }\n  if (value instanceof Map) {\n    lossy.add('Map');\n    return lossy;\n  }\n  if (value instanceof Set) {\n    lossy.add('Set');\n    return lossy;\n  }\n\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      for (const t of findLossyTypes(item, seen, depth + 1)) lossy.add(t);\n      if (lossy.size === LOSSY_TYPES.length) return lossy;\n    }\n    return lossy;\n  }\n\n  for (const k of Object.keys(value as Record<string, unknown>)) {\n    for (const t of findLossyTypes((value as Record<string, unknown>)[k], seen, depth + 1)) {\n      lossy.add(t);\n    }\n    if (lossy.size === LOSSY_TYPES.length) return lossy;\n  }\n  return lossy;\n}\n\n/** Reset warning state — for tests only. */\nexport function _resetLossyWarning(): void {\n  hasWarned = false;\n}\n"],"mappings":";AAAA,IAAM,cAAc;CAAC;CAAQ;CAAO;CAAO;AAAQ;AAEnD,IAAI,YAAY;;;;;;;;AAShB,SAAgB,mBAAmB,OAAgB,UAAwB;CACzE,IAAI,WAAW;CACf,IAAA,QAAA,IAAA,aAA6B,cAAc;CAE3C,MAAM,QAAQ,eAAe,uBAAO,IAAI,IAAI,GAAG,CAAC;CAChD,IAAI,MAAM,SAAS,GAAG;CAEtB,YAAY;CACZ,MAAM,QAAQ,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI;CAClC,QAAQ,KACN,iCAAiC,SAAS,aAAa,MAAM,8TAM/D;AACF;AAEA,SAAS,eAAe,OAAgB,MAAoB,OAA4B;CACtF,MAAM,wBAAQ,IAAI,IAAY;CAC9B,IAAI,QAAQ,KAAK,UAAU,QAAQ,UAAU,KAAA,GAAW,OAAO;CAC/D,IAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,IAAI,QAAQ;EAClB,OAAO;CACT;CACA,IAAI,OAAO,UAAU,YAAY,OAAO,UAAU,YAAY,OAAO;CACrE,IAAI,KAAK,IAAI,KAAK,GAAG,OAAO;CAC5B,KAAK,IAAI,KAAK;CAEd,IAAI,iBAAiB,MAAM;EACzB,MAAM,IAAI,MAAM;EAChB,OAAO;CACT;CACA,IAAI,iBAAiB,KAAK;EACxB,MAAM,IAAI,KAAK;EACf,OAAO;CACT;CACA,IAAI,iBAAiB,KAAK;EACxB,MAAM,IAAI,KAAK;EACf,OAAO;CACT;CAEA,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OAAO;GACxB,KAAK,MAAM,KAAK,eAAe,MAAM,MAAM,QAAQ,CAAC,GAAG,MAAM,IAAI,CAAC;GAClE,IAAI,MAAM,SAAS,YAAY,QAAQ,OAAO;EAChD;EACA,OAAO;CACT;CAEA,KAAK,MAAM,KAAK,OAAO,KAAK,KAAgC,GAAG;EAC7D,KAAK,MAAM,KAAK,eAAgB,MAAkC,IAAI,MAAM,QAAQ,CAAC,GACnF,MAAM,IAAI,CAAC;EAEb,IAAI,MAAM,SAAS,YAAY,QAAQ,OAAO;CAChD;CACA,OAAO;AACT"}

package/dist/_chunks/live-graph-D_2D32Ad.js

@@ -0,0 +1,150 @@
+import { i as scanProjectSourceFiles, t as buildSourceExtensions } from "./scan-BoP17W3w.js";
+import { a as detectDirective, n as stitchImportChains, r as classifyModule } from "./chains-Bpb0W4ax.js";
+import { n as importSignals, r as poisoningsFor, t as collectImportSpecifiers } from "./poison-scan-Bm9Yyqk9.js";
+import { normalizePath } from "vite";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+//#region src/analyze/live-graph.ts
+/**
+* live-graph — classification from a running dev server's environment
+* module graphs (the fast path).
+*
+* When a dev server runs, the env module graphs are already resident —
+* classification is a lookup, not a crawl. This module adapts those
+* graphs to the SAME classification pipeline the cold crawl uses
+* (classify.ts + chains.ts + poison-scan.ts — design/47's "one
+* classification module, thin frontends" requirement), so the
+* dev-server endpoint and the CLI can never disagree about a file.
+*
+* Differences from the crawl, both inherent to the live source:
+*
+* - The browser (`client`) graph can be non-empty here (a real browser
+*   has requested modules), so `envs.client` is confirmable.
+* - Rendering populates graphs lazily — only visited routes' code is
+*   present, and modules behind unexecuted dynamic imports carry
+*   `transformResult == null` (the §8 frontier). Those are reported as
+*   `subtreeUnknown` rather than transformed on demand: a hint must
+*   never mutate the dev server's graphs as a side effect of asking.
+*
+* Design docs: 47-module-environment-tooling.md §8, §"Dev-server
+* endpoint".
+*/
+/** Non-empty node set for a file in one graph. */
+function memberOf(graph, file) {
+	return (graph.getModulesByFile(file)?.size ?? 0) > 0;
+}
+/**
+* §8: an SSR-graph member whose every node was never transformed is a
+* module behind an unexecuted dynamic import — reachable (it ships to
+* the browser) but its subtree may be missing from the graphs.
+*
+* Live-source caveat: Vite also clears `transformResult` when a watched
+* edit invalidates a node, so on the live graphs `subtreeUnknown`
+* means "not currently transformed" — a freshly-edited module reads
+* the same as a dormant dynamic-import payload until the next render
+* re-transforms it. The two states are indistinguishable from the
+* graph alone, and both honestly mean the subtree is not currently
+* known; consumers refreshing on `timber:graph-update` events see the
+* flag clear once the module is re-transformed.
+*/
+function ssrTransformed(graph, file) {
+	const nodes = graph.getModulesByFile(file);
+	if (!nodes || nodes.size === 0) return void 0;
+	for (const node of nodes) if (node.transformResult != null) return true;
+	return false;
+}
+/**
+* Classify one file from the live graphs. `file` must be an absolute
+* realpath (graph nodes carry realpaths); it is slash-normalized here
+* to match Vite's node keying.
+*/
+async function classifyLiveFile(rawFile, ctx, getDirective = makeDirectiveReader(), errors) {
+	const file = normalizePath(rawFile);
+	let code = null;
+	try {
+		code = await readFile(file, "utf8");
+	} catch (error) {
+		errors?.push({
+			environment: "scan",
+			id: file,
+			message: `source read failed: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+	const directive = code === null ? null : detectDirective(code, file);
+	const signals = code === null ? [] : importSignals(collectImportSpecifiers(code, file));
+	const classifyCtx = {
+		appDir: ctx.appDir,
+		pageExtensions: ctx.pageExtensions
+	};
+	const classification = classifyModule({
+		file,
+		inRsc: memberOf(ctx.rsc, file),
+		inSsr: memberOf(ctx.ssr, file),
+		inClient: memberOf(ctx.client, file),
+		ssrTransformed: ssrTransformed(ctx.ssr, file),
+		directive
+	}, classifyCtx);
+	const chains = classification.pending ? [] : stitchImportChains(file, {
+		rsc: ctx.rsc,
+		ssr: ctx.ssr,
+		appDir: ctx.appDir,
+		pageExtensions: ctx.pageExtensions,
+		getDirective
+	});
+	return {
+		...classification,
+		boundary: directive === "use client",
+		chains,
+		poisonings: poisoningsFor(classification.kind, classification.pending, signals)
+	};
+}
+/**
+* Synchronous directive reader with a per-call cache. chains.ts wants a
+* sync callback; node:fs readFileSync per unique hop file is acceptable
+* for a walk bounded by chain length.
+*/
+function makeDirectiveReader() {
+	const cache = /* @__PURE__ */ new Map();
+	return (file) => {
+		const hit = cache.get(file);
+		if (hit !== void 0) return hit;
+		let directive = null;
+		try {
+			directive = detectDirective(readFileSync(file, "utf8"), file);
+		} catch {
+			directive = null;
+		}
+		cache.set(file, directive);
+		return directive;
+	};
+}
+/**
+* Classify every project source file from the live graphs. Files on
+* disk that no graph reached get the §2 provisional/pending
+* classification — on a lazily-warmed dev server that includes routes
+* nobody has visited yet, which is honest: the graphs genuinely have
+* not confirmed them.
+*/
+async function classifyLiveProject(ctx) {
+	const files = [];
+	const errors = [];
+	const extensions = buildSourceExtensions(ctx.pageExtensions);
+	await scanProjectSourceFiles(ctx.root, files, (failure) => errors.push({
+		environment: "scan",
+		id: failure.dir,
+		message: failure.message
+	}), 0, extensions);
+	const modules = [];
+	const getDirective = makeDirectiveReader();
+	for (const file of files) modules.push(await classifyLiveFile(file, ctx, getDirective, errors));
+	modules.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+	return {
+		root: ctx.root,
+		modules,
+		errors
+	};
+}
+//#endregion
+export { classifyLiveFile, classifyLiveProject };
+
+//# sourceMappingURL=live-graph-D_2D32Ad.js.map

package/dist/_chunks/live-graph-D_2D32Ad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-graph-D_2D32Ad.js","names":[],"sources":["../../src/analyze/live-graph.ts"],"sourcesContent":["/**\n * live-graph — classification from a running dev server's environment\n * module graphs (the fast path).\n *\n * When a dev server runs, the env module graphs are already resident —\n * classification is a lookup, not a crawl. This module adapts those\n * graphs to the SAME classification pipeline the cold crawl uses\n * (classify.ts + chains.ts + poison-scan.ts — design/47's \"one\n * classification module, thin frontends\" requirement), so the\n * dev-server endpoint and the CLI can never disagree about a file.\n *\n * Differences from the crawl, both inherent to the live source:\n *\n * - The browser (`client`) graph can be non-empty here (a real browser\n *   has requested modules), so `envs.client` is confirmable.\n * - Rendering populates graphs lazily — only visited routes' code is\n *   present, and modules behind unexecuted dynamic imports carry\n *   `transformResult == null` (the §8 frontier). Those are reported as\n *   `subtreeUnknown` rather than transformed on demand: a hint must\n *   never mutate the dev server's graphs as a side effect of asking.\n *\n * Design docs: 47-module-environment-tooling.md §8, §\"Dev-server\n * endpoint\".\n */\n\nimport { readFile } from 'node:fs/promises';\nimport { readFileSync } from 'node:fs';\nimport { normalizePath } from 'vite';\nimport {\n  classifyModule,\n  detectDirective,\n  type ClassifyContext,\n  type Directive,\n} from './classify.ts';\nimport type { GraphModuleReport } from './crawl.ts';\nimport { stitchImportChains, type ChainGraph, type ImportChain } from './chains.ts';\nimport {\n  collectImportSpecifiers,\n  importSignals,\n  poisoningsFor,\n  type Poisoning,\n} from './poison-scan.ts';\nimport { buildSourceExtensions, scanProjectSourceFiles, type ScanFailure } from './scan.ts';\n\n/**\n * Duck-typed node view for liveness checks — the `transformResult`\n * member ChainModuleNode deliberately omits (§8 detection is a\n * classification concern, not a chain concern).\n */\ninterface LiveModuleNode {\n  transformResult: unknown;\n}\n\nimport type { ChainModuleNode } from './chains.ts';\n\n/** Duck-typed module graph — structural supertype of Vite's. */\nexport interface LiveGraph extends ChainGraph {\n  getModulesByFile(file: string): Set<ChainModuleNode & LiveModuleNode> | undefined;\n}\n\nexport interface LiveGraphContext {\n  rsc: LiveGraph;\n  ssr: LiveGraph;\n  client: LiveGraph;\n  /** Realpath'd project root. */\n  root: string;\n  appDir: string;\n  pageExtensions?: readonly string[];\n}\n\n/**\n * Per-module answer — the crawl's shape, aliased rather than restated\n * so a field added to one frontend cannot silently miss the other.\n */\nexport type LiveModuleReport = GraphModuleReport;\n\n/** Non-empty node set for a file in one graph. */\nfunction memberOf(graph: LiveGraph, file: string): boolean {\n  return (graph.getModulesByFile(file)?.size ?? 0) > 0;\n}\n\n/**\n * §8: an SSR-graph member whose every node was never transformed is a\n * module behind an unexecuted dynamic import — reachable (it ships to\n * the browser) but its subtree may be missing from the graphs.\n *\n * Live-source caveat: Vite also clears `transformResult` when a watched\n * edit invalidates a node, so on the live graphs `subtreeUnknown`\n * means \"not currently transformed\" — a freshly-edited module reads\n * the same as a dormant dynamic-import payload until the next render\n * re-transforms it. The two states are indistinguishable from the\n * graph alone, and both honestly mean the subtree is not currently\n * known; consumers refreshing on `timber:graph-update` events see the\n * flag clear once the module is re-transformed.\n */\nfunction ssrTransformed(graph: LiveGraph, file: string): boolean | undefined {\n  const nodes = graph.getModulesByFile(file);\n  if (!nodes || nodes.size === 0) return undefined;\n  for (const node of nodes) {\n    if (node.transformResult != null) return true;\n  }\n  return false;\n}\n\n/**\n * Classify one file from the live graphs. `file` must be an absolute\n * realpath (graph nodes carry realpaths); it is slash-normalized here\n * to match Vite's node keying.\n */\nexport async function classifyLiveFile(\n  rawFile: string,\n  ctx: LiveGraphContext,\n  // Shared across a ?all=1 sweep (classifyLiveProject) — a per-call\n  // cache would re-read every chain hop's source per target file,\n  // quadratic sync IO on well-connected graphs.\n  getDirective: (file: string) => Directive = makeDirectiveReader(),\n  // Failures are recorded, not swallowed (crawl parity): a lost source\n  // read means the directive/poisoning half of the answer is missing,\n  // and consumers deserve to see that beside the classification.\n  errors?: LiveGraphError[]\n): Promise<LiveModuleReport> {\n  const file = normalizePath(rawFile);\n  let code: string | null = null;\n  try {\n    code = await readFile(file, 'utf8');\n  } catch (error) {\n    // Unreadable (deleted mid-query): classification proceeds on graph\n    // membership alone; directive/poisonings default to none.\n    errors?.push({\n      environment: 'scan',\n      id: file,\n      message: `source read failed: ${error instanceof Error ? error.message : String(error)}`,\n    });\n  }\n  const directive: Directive = code === null ? null : detectDirective(code, file);\n  const signals = code === null ? [] : importSignals(collectImportSpecifiers(code, file));\n\n  const classifyCtx: ClassifyContext = {\n    appDir: ctx.appDir,\n    pageExtensions: ctx.pageExtensions,\n  };\n  const classification = classifyModule(\n    {\n      file,\n      inRsc: memberOf(ctx.rsc, file),\n      inSsr: memberOf(ctx.ssr, file),\n      inClient: memberOf(ctx.client, file),\n      ssrTransformed: ssrTransformed(ctx.ssr, file),\n      directive,\n    },\n    classifyCtx\n  );\n\n  const chains = classification.pending\n    ? []\n    : stitchImportChains(file, {\n        rsc: ctx.rsc,\n        ssr: ctx.ssr,\n        appDir: ctx.appDir,\n        pageExtensions: ctx.pageExtensions,\n        getDirective,\n      });\n\n  return {\n    ...classification,\n    boundary: directive === 'use client',\n    chains,\n    poisonings: poisoningsFor(classification.kind, classification.pending, signals),\n  };\n}\n\n/**\n * Synchronous directive reader with a per-call cache. chains.ts wants a\n * sync callback; node:fs readFileSync per unique hop file is acceptable\n * for a walk bounded by chain length.\n */\nfunction makeDirectiveReader(): (file: string) => Directive {\n  const cache = new Map<string, Directive>();\n  return (file) => {\n    const hit = cache.get(file);\n    if (hit !== undefined) return hit;\n    let directive: Directive = null;\n    try {\n      directive = detectDirective(readFileSync(file, 'utf8'), file);\n    } catch {\n      directive = null;\n    }\n    cache.set(file, directive);\n    return directive;\n  };\n}\n\n/** Live-source error entry — the crawl's error vocabulary. */\nexport interface LiveGraphError {\n  environment: 'scan';\n  id: string;\n  message: string;\n}\n\nexport interface LiveProjectReport {\n  root: string;\n  modules: LiveModuleReport[];\n  errors: LiveGraphError[];\n}\n\n/**\n * Classify every project source file from the live graphs. Files on\n * disk that no graph reached get the §2 provisional/pending\n * classification — on a lazily-warmed dev server that includes routes\n * nobody has visited yet, which is honest: the graphs genuinely have\n * not confirmed them.\n */\nexport async function classifyLiveProject(ctx: LiveGraphContext): Promise<LiveProjectReport> {\n  const files: string[] = [];\n  const errors: LiveProjectReport['errors'] = [];\n  const extensions = buildSourceExtensions(ctx.pageExtensions);\n  await scanProjectSourceFiles(\n    ctx.root,\n    files,\n    (failure: ScanFailure) =>\n      errors.push({ environment: 'scan', id: failure.dir, message: failure.message }),\n    0,\n    extensions\n  );\n  const modules: LiveModuleReport[] = [];\n  const getDirective = makeDirectiveReader();\n  for (const file of files) {\n    modules.push(await classifyLiveFile(file, ctx, getDirective, errors));\n  }\n  modules.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n  return { root: ctx.root, modules, errors };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,SAAS,SAAS,OAAkB,MAAuB;CACzD,QAAQ,MAAM,iBAAiB,IAAI,CAAC,EAAE,QAAQ,KAAK;AACrD;;;;;;;;;;;;;;;AAgBA,SAAS,eAAe,OAAkB,MAAmC;CAC3E,MAAM,QAAQ,MAAM,iBAAiB,IAAI;CACzC,IAAI,CAAC,SAAS,MAAM,SAAS,GAAG,OAAO,KAAA;CACvC,KAAK,MAAM,QAAQ,OACjB,IAAI,KAAK,mBAAmB,MAAM,OAAO;CAE3C,OAAO;AACT;;;;;;AAOA,eAAsB,iBACpB,SACA,KAIA,eAA4C,oBAAoB,GAIhE,QAC2B;CAC3B,MAAM,OAAO,cAAc,OAAO;CAClC,IAAI,OAAsB;CAC1B,IAAI;EACF,OAAO,MAAM,SAAS,MAAM,MAAM;CACpC,SAAS,OAAO;EAGd,QAAQ,KAAK;GACX,aAAa;GACb,IAAI;GACJ,SAAS,uBAAuB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACvF,CAAC;CACH;CACA,MAAM,YAAuB,SAAS,OAAO,OAAO,gBAAgB,MAAM,IAAI;CAC9E,MAAM,UAAU,SAAS,OAAO,CAAC,IAAI,cAAc,wBAAwB,MAAM,IAAI,CAAC;CAEtF,MAAM,cAA+B;EACnC,QAAQ,IAAI;EACZ,gBAAgB,IAAI;CACtB;CACA,MAAM,iBAAiB,eACrB;EACE;EACA,OAAO,SAAS,IAAI,KAAK,IAAI;EAC7B,OAAO,SAAS,IAAI,KAAK,IAAI;EAC7B,UAAU,SAAS,IAAI,QAAQ,IAAI;EACnC,gBAAgB,eAAe,IAAI,KAAK,IAAI;EAC5C;CACF,GACA,WACF;CAEA,MAAM,SAAS,eAAe,UAC1B,CAAC,IACD,mBAAmB,MAAM;EACvB,KAAK,IAAI;EACT,KAAK,IAAI;EACT,QAAQ,IAAI;EACZ,gBAAgB,IAAI;EACpB;CACF,CAAC;CAEL,OAAO;EACL,GAAG;EACH,UAAU,cAAc;EACxB;EACA,YAAY,cAAc,eAAe,MAAM,eAAe,SAAS,OAAO;CAChF;AACF;;;;;;AAOA,SAAS,sBAAmD;CAC1D,MAAM,wBAAQ,IAAI,IAAuB;CACzC,QAAQ,SAAS;EACf,MAAM,MAAM,MAAM,IAAI,IAAI;EAC1B,IAAI,QAAQ,KAAA,GAAW,OAAO;EAC9B,IAAI,YAAuB;EAC3B,IAAI;GACF,YAAY,gBAAgB,aAAa,MAAM,MAAM,GAAG,IAAI;EAC9D,QAAQ;GACN,YAAY;EACd;EACA,MAAM,IAAI,MAAM,SAAS;EACzB,OAAO;CACT;AACF;;;;;;;;AAsBA,eAAsB,oBAAoB,KAAmD;CAC3F,MAAM,QAAkB,CAAC;CACzB,MAAM,SAAsC,CAAC;CAC7C,MAAM,aAAa,sBAAsB,IAAI,cAAc;CAC3D,MAAM,uBACJ,IAAI,MACJ,QACC,YACC,OAAO,KAAK;EAAE,aAAa;EAAQ,IAAI,QAAQ;EAAK,SAAS,QAAQ;CAAQ,CAAC,GAChF,GACA,UACF;CACA,MAAM,UAA8B,CAAC;CACrC,MAAM,eAAe,oBAAoB;CACzC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,MAAM,iBAAiB,MAAM,KAAK,cAAc,MAAM,CAAC;CAEtE,QAAQ,MAAM,GAAG,MAAO,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,CAAE;CACvE,OAAO;EAAE,MAAM,IAAI;EAAM;EAAS;CAAO;AAC3C"}