@nextera.one/anchor-routing-core 0.1.0

package/dist/index.js

@@ -0,0 +1,826 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ANCHOR_ERROR_CODES: () => ANCHOR_ERROR_CODES,
+  ANCHOR_PATH_PREFIX: () => ANCHOR_PATH_PREFIX,
+  ANCHOR_SEPARATOR: () => ANCHOR_SEPARATOR,
+  ARG_SEPARATOR: () => ARG_SEPARATOR,
+  AnchorRouteError: () => AnchorRouteError,
+  DOT_SEPARATOR: () => DOT_SEPARATOR,
+  RESERVED_ANCHOR_CHARACTERS: () => RESERVED_ANCHOR_CHARACTERS,
+  SAFE_LITERAL_CHARACTER: () => SAFE_LITERAL_CHARACTER,
+  buildDotAnchor: () => buildDotAnchor,
+  buildIntentAnchor: () => buildIntentAnchor,
+  buildPageAnchor: () => buildPageAnchor,
+  buildParamAnchor: () => buildParamAnchor,
+  createDiagnostic: () => createDiagnostic,
+  decodeAnchorKey: () => decodeAnchorKey,
+  decodeAnchorToken: () => decodeAnchorToken,
+  escapeAnchorKey: () => escapeAnchorKey,
+  escapeAnchorValue: () => escapeAnchorValue,
+  isAnchorRoute: () => isAnchorRoute,
+  isAnchorRouteError: () => isAnchorRouteError,
+  isHexDigit: () => isHexDigit,
+  isReservedAnchorCharacter: () => isReservedAnchorCharacter,
+  normalizeAnchor: () => normalizeAnchor,
+  parseAnchor: () => parseAnchor,
+  resolveAnchor: () => resolveAnchor,
+  serializeAnchor: () => serializeAnchor,
+  validateAnchor: () => validateAnchor,
+  validateEncodedToken: () => validateEncodedToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var ANCHOR_PATH_PREFIX = "/~";
+var ARG_SEPARATOR = ";";
+var ANCHOR_SEPARATOR = "~";
+var DOT_SEPARATOR = ".";
+var RESERVED_ANCHOR_CHARACTERS = ["/", "~", ";", ".", "=", "@", "#", "%"];
+var reservedAnchorCharacterSet = new Set(RESERVED_ANCHOR_CHARACTERS);
+var SAFE_LITERAL_CHARACTER = /^[A-Za-z0-9_-]$/;
+function isReservedAnchorCharacter(character) {
+  return reservedAnchorCharacterSet.has(character);
+}
+function isHexDigit(character) {
+  return /^[0-9A-Fa-f]$/.test(character);
+}
+
+// src/errors.ts
+var ANCHOR_ERROR_CODES = {
+  ANCHOR_PARSE_EMPTY_INPUT: "ANCHOR_PARSE_EMPTY_INPUT",
+  ANCHOR_PARSE_INVALID_FORMAT: "ANCHOR_PARSE_INVALID_FORMAT",
+  ANCHOR_PARSE_EMPTY_PAGE: "ANCHOR_PARSE_EMPTY_PAGE",
+  ANCHOR_PARSE_EMPTY_SECTION: "ANCHOR_PARSE_EMPTY_SECTION",
+  ANCHOR_PARSE_EMPTY_KEY: "ANCHOR_PARSE_EMPTY_KEY",
+  ANCHOR_PARSE_INVALID_DOT_KEY: "ANCHOR_PARSE_INVALID_DOT_KEY",
+  ANCHOR_PARSE_INVALID_INTENT_PAIR: "ANCHOR_PARSE_INVALID_INTENT_PAIR",
+  ANCHOR_PARSE_DUPLICATE_NAMED_ARG: "ANCHOR_PARSE_DUPLICATE_NAMED_ARG",
+  ANCHOR_ESCAPE_INVALID_SEQUENCE: "ANCHOR_ESCAPE_INVALID_SEQUENCE",
+  ANCHOR_VALIDATE_UNESCAPED_RESERVED_CHAR: "ANCHOR_VALIDATE_UNESCAPED_RESERVED_CHAR",
+  ANCHOR_VALIDATE_TOO_MANY_ARGS: "ANCHOR_VALIDATE_TOO_MANY_ARGS",
+  ANCHOR_RESOLVE_PAGE_NOT_FOUND: "ANCHOR_RESOLVE_PAGE_NOT_FOUND",
+  ANCHOR_RESOLVE_SECTION_NOT_FOUND: "ANCHOR_RESOLVE_SECTION_NOT_FOUND",
+  ANCHOR_RESOLVE_KEY_NOT_FOUND: "ANCHOR_RESOLVE_KEY_NOT_FOUND",
+  ANCHOR_RESOLVE_BINDING_MISSING_ARG: "ANCHOR_RESOLVE_BINDING_MISSING_ARG",
+  ANCHOR_RESOLVE_INVALID_NAMED_ARG: "ANCHOR_RESOLVE_INVALID_NAMED_ARG"
+};
+var AnchorRouteError = class extends Error {
+  code;
+  raw;
+  mode;
+  constructor(code, message, raw, mode) {
+    super(message);
+    this.name = "AnchorRouteError";
+    this.code = code;
+    this.raw = raw;
+    this.mode = mode;
+  }
+  toDiagnostic() {
+    return {
+      code: this.code,
+      message: this.message,
+      raw: this.raw,
+      mode: this.mode
+    };
+  }
+};
+function createDiagnostic(code, message, raw, mode) {
+  return { code, message, raw, mode };
+}
+function isAnchorRouteError(error) {
+  return error instanceof AnchorRouteError;
+}
+
+// src/escape.ts
+var encoder = new TextEncoder();
+function encodeCharacter(character) {
+  return Array.from(encoder.encode(character)).map((byte) => `%${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("");
+}
+function escapeAnchorValue(input) {
+  const value = String(input ?? "");
+  let output = "";
+  for (const character of value) {
+    output += SAFE_LITERAL_CHARACTER.test(character) ? character : encodeCharacter(character);
+  }
+  return output;
+}
+function validateEncodedToken(rawToken, rawInput, mode) {
+  for (let index = 0; index < rawToken.length; index += 1) {
+    const character = rawToken[index];
+    if (character === "%") {
+      const high = rawToken[index + 1];
+      const low = rawToken[index + 2];
+      if (!high || !low || !isHexDigit(high) || !isHexDigit(low)) {
+        throw new AnchorRouteError(
+          ANCHOR_ERROR_CODES.ANCHOR_ESCAPE_INVALID_SEQUENCE,
+          `Invalid percent-escape sequence in "${rawToken}".`,
+          rawInput,
+          mode
+        );
+      }
+      index += 2;
+      continue;
+    }
+    if (isReservedAnchorCharacter(character)) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_VALIDATE_UNESCAPED_RESERVED_CHAR,
+        `Reserved character "${character}" must be percent-encoded inside anchor values.`,
+        rawInput,
+        mode
+      );
+    }
+  }
+}
+function decodeAnchorToken(rawToken, rawInput, mode) {
+  validateEncodedToken(rawToken, rawInput, mode);
+  try {
+    return decodeURIComponent(rawToken);
+  } catch {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_ESCAPE_INVALID_SEQUENCE,
+      `Invalid percent-escape sequence in "${rawToken}".`,
+      rawInput,
+      mode
+    );
+  }
+}
+function decodeAnchorKey(rawKey, rawInput, mode) {
+  if (!rawKey) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_KEY,
+      "Anchor route key cannot be empty.",
+      rawInput,
+      mode
+    );
+  }
+  const rawSegments = rawKey.split(DOT_SEPARATOR);
+  if (rawSegments.some((segment) => segment.length === 0)) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_DOT_KEY,
+      `Dot key "${rawKey}" contains an empty path token.`,
+      rawInput,
+      mode
+    );
+  }
+  const pathTokens = rawSegments.map((segment) => {
+    const decoded = decodeAnchorToken(segment, rawInput, mode);
+    if (decoded.includes(DOT_SEPARATOR)) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_DOT_KEY,
+        `Dot key segment "${decoded}" must not decode to another dot separator.`,
+        rawInput,
+        mode
+      );
+    }
+    return decoded;
+  });
+  return {
+    key: pathTokens.join(DOT_SEPARATOR),
+    pathTokens
+  };
+}
+function escapeAnchorKey(input) {
+  const rawKey = String(input ?? "").trim();
+  if (!rawKey) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_KEY,
+      "Anchor route key cannot be empty.",
+      rawKey
+    );
+  }
+  const segments = rawKey.split(DOT_SEPARATOR).map((segment) => segment.trim());
+  if (segments.some((segment) => !segment)) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_DOT_KEY,
+      `Dot key "${rawKey}" contains an empty path token.`,
+      rawKey
+    );
+  }
+  return segments.map((segment) => escapeAnchorValue(segment)).join(DOT_SEPARATOR);
+}
+
+// src/builders.ts
+function requireValue(value, code, message) {
+  const trimmed = String(value ?? "").trim();
+  if (!trimmed) {
+    throw new AnchorRouteError(code, message, String(value ?? ""));
+  }
+  return trimmed;
+}
+function buildPageAnchor(page, section) {
+  const safePage = escapeAnchorValue(requireValue(page, ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_PAGE, "Page value cannot be empty."));
+  const safeSection = escapeAnchorValue(
+    requireValue(section, ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_SECTION, "Section value cannot be empty.")
+  );
+  return `/${safePage}${ANCHOR_SEPARATOR}${safeSection}`;
+}
+function buildParamAnchor(key, args = []) {
+  const safeKey = escapeAnchorKey(key);
+  const encodedArgs = args.map((argument) => escapeAnchorValue(String(argument ?? "")));
+  return `${ANCHOR_PATH_PREFIX}${safeKey}${encodedArgs.map((argument) => `${ARG_SEPARATOR}${argument}`).join("")}`;
+}
+function buildDotAnchor(tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_DOT_KEY,
+      "Dot case requires at least one token.",
+      String(tokens ?? "")
+    );
+  }
+  const key = tokens.map((token) => requireValue(token, ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_DOT_KEY, "Dot token cannot be empty.")).join(DOT_SEPARATOR);
+  return `${ANCHOR_PATH_PREFIX}${escapeAnchorKey(key)}`;
+}
+function buildIntentAnchor(key, namedArgs) {
+  const safeKey = escapeAnchorKey(key);
+  const pairs = Object.entries(namedArgs ?? {});
+  if (pairs.length === 0) {
+    return `${ANCHOR_PATH_PREFIX}${safeKey}`;
+  }
+  const encodedPairs = pairs.map(([name, value]) => {
+    const safeName = escapeAnchorValue(
+      requireValue(name, ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_INTENT_PAIR, "Intent argument name cannot be empty.")
+    );
+    const safeValue = escapeAnchorValue(
+      requireValue(value, ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_INTENT_PAIR, `Intent argument "${name}" cannot be empty.`)
+    );
+    return `${ARG_SEPARATOR}${safeName}${DOT_SEPARATOR}${safeValue}`;
+  });
+  return `${ANCHOR_PATH_PREFIX}${safeKey}${encodedPairs.join("")}`;
+}
+function serializeAnchor(instruction) {
+  switch (instruction.mode) {
+    case "page":
+      return buildPageAnchor(instruction.page ?? "", instruction.section ?? "");
+    case "param":
+      return buildParamAnchor(instruction.key ?? "", instruction.args ?? []);
+    case "dot":
+      return buildDotAnchor(instruction.pathTokens ?? (instruction.key ? instruction.key.split(DOT_SEPARATOR) : []));
+    case "intent":
+      return buildIntentAnchor(instruction.key ?? "", instruction.namedArgs ?? {});
+    default:
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+        `Unsupported anchor route mode "${String(instruction.mode)}".`,
+        instruction.raw
+      );
+  }
+}
+
+// src/normalize.ts
+function normalizeAnchor(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) {
+    return "";
+  }
+  let normalized = raw;
+  if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(normalized)) {
+    try {
+      const url = new URL(normalized);
+      normalized = url.pathname || "/";
+    } catch {
+      normalized = raw;
+    }
+  }
+  const suffixIndex = normalized.search(/[?#]/);
+  if (suffixIndex >= 0) {
+    normalized = normalized.slice(0, suffixIndex);
+  }
+  if (!normalized.startsWith("/")) {
+    normalized = `/${normalized}`;
+  }
+  normalized = normalized.replace(/\/{2,}/g, "/");
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+// src/parser.ts
+function parsePageRoute(normalized) {
+  const body = normalized.slice(1);
+  if (body.includes("/")) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+      "Page Case must use a single path segment in the form /page~section.",
+      normalized,
+      "page"
+    );
+  }
+  const parts = body.split(ANCHOR_SEPARATOR);
+  if (parts.length !== 2) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+      "Page Case must contain exactly one ~ separator.",
+      normalized,
+      "page"
+    );
+  }
+  const [rawPage, rawSection] = parts;
+  if (!rawPage) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_PAGE,
+      "Page Case requires a non-empty page value.",
+      normalized,
+      "page"
+    );
+  }
+  if (!rawSection) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_SECTION,
+      "Page Case requires a non-empty section value.",
+      normalized,
+      "page"
+    );
+  }
+  return {
+    mode: "page",
+    raw: normalized,
+    page: decodeAnchorToken(rawPage, normalized, "page"),
+    section: decodeAnchorToken(rawSection, normalized, "page")
+  };
+}
+function parseDotRoute(normalized, rawKey) {
+  const key = decodeAnchorKey(rawKey, normalized, "dot");
+  return {
+    mode: "dot",
+    raw: normalized,
+    key: key.key,
+    pathTokens: key.pathTokens
+  };
+}
+function parseParamRoute(normalized, rawKey, payload) {
+  const key = decodeAnchorKey(rawKey, normalized, "param");
+  const args = payload.map((rawArgument) => {
+    if (!rawArgument) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+        "Param Case does not allow empty positional arguments.",
+        normalized,
+        "param"
+      );
+    }
+    return decodeAnchorToken(rawArgument, normalized, "param");
+  });
+  return {
+    mode: "param",
+    raw: normalized,
+    key: key.key,
+    pathTokens: key.pathTokens,
+    args
+  };
+}
+function parseIntentRoute(normalized, rawKey, payload) {
+  const key = decodeAnchorKey(rawKey, normalized, "intent");
+  const namedArgs = {};
+  for (const rawPair of payload) {
+    const separatorIndex = rawPair.indexOf(DOT_SEPARATOR);
+    if (separatorIndex <= 0 || separatorIndex === rawPair.length - 1) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_INTENT_PAIR,
+        `Intent Case pair "${rawPair}" must use the form name.value.`,
+        normalized,
+        "intent"
+      );
+    }
+    const rawName = rawPair.slice(0, separatorIndex);
+    const rawValue = rawPair.slice(separatorIndex + 1);
+    const name = decodeAnchorToken(rawName, normalized, "intent");
+    const value = decodeAnchorToken(rawValue, normalized, "intent");
+    if (Object.prototype.hasOwnProperty.call(namedArgs, name)) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_DUPLICATE_NAMED_ARG,
+        `Intent Case contains duplicate named argument "${name}".`,
+        normalized,
+        "intent"
+      );
+    }
+    namedArgs[name] = value;
+  }
+  return {
+    mode: "intent",
+    raw: normalized,
+    key: key.key,
+    pathTokens: key.pathTokens,
+    namedArgs
+  };
+}
+function parseAnchor(input) {
+  const normalized = normalizeAnchor(input);
+  if (!normalized) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_INPUT,
+      "Anchor route input cannot be empty.",
+      String(input ?? "")
+    );
+  }
+  if (!normalized.startsWith(ANCHOR_PATH_PREFIX) && normalized.includes(ANCHOR_SEPARATOR)) {
+    return parsePageRoute(normalized);
+  }
+  if (!normalized.startsWith(ANCHOR_PATH_PREFIX)) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+      "Input is not an Anchor Route.",
+      normalized
+    );
+  }
+  const capsuleBody = normalized.slice(ANCHOR_PATH_PREFIX.length);
+  if (!capsuleBody || capsuleBody.includes("/")) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+      "Capsule cases must use the form /~key or /~key;payload.",
+      normalized
+    );
+  }
+  const [rawKey, ...payload] = capsuleBody.split(ARG_SEPARATOR);
+  if (!rawKey) {
+    throw new AnchorRouteError(
+      ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_KEY,
+      "Capsule cases require a non-empty route key.",
+      normalized
+    );
+  }
+  if (payload.length === 0) {
+    if (rawKey.includes(DOT_SEPARATOR)) {
+      return parseDotRoute(normalized, rawKey);
+    }
+    return parseParamRoute(normalized, rawKey, []);
+  }
+  const payloadHasDot = payload.some((segment) => segment.includes(DOT_SEPARATOR));
+  const payloadAllNamedPairs = payload.every((segment) => {
+    const dotIndex = segment.indexOf(DOT_SEPARATOR);
+    return dotIndex > 0 && dotIndex < segment.length - 1 && segment.indexOf(DOT_SEPARATOR, dotIndex + 1) === -1;
+  });
+  if (payloadHasDot) {
+    if (!payloadAllNamedPairs) {
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_INTENT_PAIR,
+        "Intent Case payload must use only name.value pairs.",
+        normalized,
+        "intent"
+      );
+    }
+    return parseIntentRoute(normalized, rawKey, payload);
+  }
+  return parseParamRoute(normalized, rawKey, payload);
+}
+function isAnchorRoute(input) {
+  try {
+    parseAnchor(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/validate.ts
+function highestPositionalIndex(instruction, registry) {
+  if (instruction.mode !== "param" || !instruction.key) {
+    return -1;
+  }
+  const definition = registry?.global?.[instruction.key];
+  if (!definition?.positionalBind) {
+    return -1;
+  }
+  return Math.max(...Object.values(definition.positionalBind), -1);
+}
+function validateAnchor(input, registry, options = {}) {
+  let instruction;
+  try {
+    instruction = typeof input === "string" ? parseAnchor(input) : input;
+  } catch (error) {
+    if (isAnchorRouteError(error)) {
+      return { valid: false, errors: [error.toDiagnostic()] };
+    }
+    throw error;
+  }
+  const errors = [];
+  switch (instruction.mode) {
+    case "page": {
+      if (!instruction.page) {
+        errors.push(createDiagnostic(ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_PAGE, "Page Case requires a page value.", instruction.raw, "page"));
+      }
+      if (!instruction.section) {
+        errors.push(createDiagnostic(ANCHOR_ERROR_CODES.ANCHOR_PARSE_EMPTY_SECTION, "Page Case requires a section value.", instruction.raw, "page"));
+      }
+      if (instruction.page && registry?.pages && !registry.pages[instruction.page]) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_PAGE_NOT_FOUND,
+            `No page registry entry exists for "${instruction.page}".`,
+            instruction.raw,
+            "page"
+          )
+        );
+      }
+      if (instruction.page && instruction.section && registry?.pages?.[instruction.page] && !registry.pages[instruction.page][instruction.section]) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_SECTION_NOT_FOUND,
+            `No page section registry entry exists for "${instruction.page}~${instruction.section}".`,
+            instruction.raw,
+            "page"
+          )
+        );
+      }
+      break;
+    }
+    case "param": {
+      const definition = instruction.key ? registry?.global?.[instruction.key] : void 0;
+      if (instruction.key && registry?.global && !definition) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_KEY_NOT_FOUND,
+            `No global registry entry exists for key "${instruction.key}".`,
+            instruction.raw,
+            "param"
+          )
+        );
+      }
+      const requiredCount = definition?.requiredPositionalCount ?? highestPositionalIndex(instruction, registry) + 1;
+      if ((instruction.args?.length ?? 0) < requiredCount) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_BINDING_MISSING_ARG,
+            `Param Case key "${instruction.key}" expects at least ${requiredCount} positional arguments.`,
+            instruction.raw,
+            "param"
+          )
+        );
+      }
+      if (options.maxArgs != null && (instruction.args?.length ?? 0) > options.maxArgs) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_VALIDATE_TOO_MANY_ARGS,
+            `Param Case exceeds the maximum allowed positional argument count of ${options.maxArgs}.`,
+            instruction.raw,
+            "param"
+          )
+        );
+      }
+      break;
+    }
+    case "dot": {
+      if (instruction.key && registry?.global && !registry.global[instruction.key]) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_KEY_NOT_FOUND,
+            `No global registry entry exists for key "${instruction.key}".`,
+            instruction.raw,
+            "dot"
+          )
+        );
+      }
+      break;
+    }
+    case "intent": {
+      const definition = instruction.key ? registry?.global?.[instruction.key] : void 0;
+      if (instruction.key && registry?.global && !definition) {
+        errors.push(
+          createDiagnostic(
+            ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_KEY_NOT_FOUND,
+            `No global registry entry exists for key "${instruction.key}".`,
+            instruction.raw,
+            "intent"
+          )
+        );
+        break;
+      }
+      const requiredNames = definition?.requiredNamedArgs ?? Object.values(definition?.namedBind ?? {});
+      for (const requiredName of requiredNames) {
+        if (!instruction.namedArgs || !Object.prototype.hasOwnProperty.call(instruction.namedArgs, requiredName)) {
+          errors.push(
+            createDiagnostic(
+              ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_BINDING_MISSING_ARG,
+              `Intent Case key "${instruction.key}" requires named argument "${requiredName}".`,
+              instruction.raw,
+              "intent"
+            )
+          );
+        }
+      }
+      if (definition?.namedBind && instruction.namedArgs) {
+        const allowedNames = new Set(Object.values(definition.namedBind));
+        for (const name of Object.keys(instruction.namedArgs)) {
+          if (!allowedNames.has(name) && (options.unknownNamedArgs ?? "reject") === "reject") {
+            errors.push(
+              createDiagnostic(
+                ANCHOR_ERROR_CODES.ANCHOR_RESOLVE_INVALID_NAMED_ARG,
+                `Intent Case key "${instruction.key}" does not allow named argument "${name}".`,
+                instruction.raw,
+                "intent"
+              )
+            );
+          }
+        }
+      }
+      break;
+    }
+    default:
+      throw new AnchorRouteError(
+        ANCHOR_ERROR_CODES.ANCHOR_PARSE_INVALID_FORMAT,
+        `Unsupported route mode "${String(instruction.mode)}".`,
+        instruction.raw
+      );
+  }
+  return {
+    valid: errors.length === 0,
+    instruction,
+    errors
+  };
+}
+
+// src/resolve.ts
+function pickBindingTarget(definition, field) {
+  return definition.bindingTargets?.[field] ?? "params";
+}
+function assignBoundValue(field, value, definition, params, query) {
+  if (pickBindingTarget(definition, field) === "query") {
+    query[field] = value;
+    return;
+  }
+  params[field] = value;
+}
+function buildResolvedRoute(instruction, definition, extraMeta = {}) {
+  const params = { ...definition.defaultParams ?? {} };
+  const query = { ...definition.defaultQuery ?? {} };
+  if (instruction.mode === "param" && definition.positionalBind) {
+    for (const [field, index] of Object.entries(definition.positionalBind)) {
+      const value = instruction.args?.[index];
+      if (value != null) {
+        assignBoundValue(field, value, definition, params, query);
+      }
+    }
+  }
+  if (instruction.mode === "intent" && definition.namedBind) {
+    for (const [field, sourceName] of Object.entries(definition.namedBind)) {
+      const value = instruction.namedArgs?.[sourceName];
+      if (value != null) {
+        assignBoundValue(field, value, definition, params, query);
+      }
+    }
+  }
+  return {
+    success: true,
+    mode: instruction.mode,
+    raw: instruction.raw,
+    name: definition.name,
+    path: definition.path,
+    params: Object.keys(params).length > 0 ? params : void 0,
+    query: Object.keys(query).length > 0 ? query : void 0,
+    hash: definition.hash,
+    title: definition.title,
+    permissions: definition.permissions,
+    meta: {
+      ...definition.meta,
+      ...extraMeta,
+      instruction
+    }
+  };
+}
+function errorResult(raw, mode, code, message, diagnostics = code ? [createDiagnostic(code, message, raw, mode)] : void 0) {
+  return {
+    success: false,
+    mode,
+    raw,
+    errorCode: code,
+    errorMessage: message,
+    diagnostics
+  };
+}
+function resolveAnchor(input, registry = {}, options = {}) {
+  let instruction;
+  try {
+    instruction = typeof input === "string" ? parseAnchor(input) : input;
+  } catch (error) {
+    if (isAnchorRouteError(error)) {
+      return {
+        success: false,
+        mode: "unknown",
+        raw: error.raw,
+        errorCode: error.code,
+        errorMessage: error.message,
+        diagnostics: [error.toDiagnostic()]
+      };
+    }
+    throw error;
+  }
+  const validation = validateAnchor(instruction, registry, options);
+  if (!validation.valid) {
+    const [firstDiagnostic] = validation.errors;
+    return {
+      success: false,
+      mode: instruction.mode,
+      raw: instruction.raw,
+      errorCode: firstDiagnostic?.code,
+      errorMessage: firstDiagnostic?.message,
+      diagnostics: validation.errors
+    };
+  }
+  switch (instruction.mode) {
+    case "page": {
+      const definition = registry.pages?.[instruction.page ?? ""]?.[instruction.section ?? ""];
+      if (!definition) {
+        return errorResult(
+          instruction.raw,
+          "page",
+          validation.errors[0]?.code ?? "ANCHOR_RESOLVE_PAGE_NOT_FOUND",
+          validation.errors[0]?.message ?? `Page Case could not be resolved for "${instruction.page}~${instruction.section}".`,
+          validation.errors.length > 0 ? validation.errors : void 0
+        );
+      }
+      return buildResolvedRoute(instruction, definition, {
+        page: instruction.page,
+        section: instruction.section
+      });
+    }
+    case "param": {
+      const definition = registry.global?.[instruction.key ?? ""];
+      if (!definition) {
+        return errorResult(instruction.raw, "param", validation.errors[0]?.code, validation.errors[0]?.message ?? "Param Case could not be resolved.", validation.errors);
+      }
+      return buildResolvedRoute(instruction, definition, {
+        key: instruction.key,
+        args: instruction.args ?? []
+      });
+    }
+    case "dot": {
+      const definition = registry.global?.[instruction.key ?? ""];
+      if (!definition) {
+        return errorResult(instruction.raw, "dot", validation.errors[0]?.code, validation.errors[0]?.message ?? "Dot Case could not be resolved.", validation.errors);
+      }
+      return buildResolvedRoute(instruction, definition, {
+        key: instruction.key,
+        pathTokens: instruction.pathTokens ?? []
+      });
+    }
+    case "intent": {
+      const definition = registry.global?.[instruction.key ?? ""];
+      if (!definition) {
+        return errorResult(instruction.raw, "intent", validation.errors[0]?.code, validation.errors[0]?.message ?? "Intent Case could not be resolved.", validation.errors);
+      }
+      const allowedNames = new Set(Object.values(definition.namedBind ?? {}));
+      const unknownNamedArgs = Object.entries(instruction.namedArgs ?? {}).filter(([name]) => !allowedNames.has(name));
+      const meta = {
+        key: instruction.key,
+        namedArgs: instruction.namedArgs ?? {}
+      };
+      if ((options.unknownNamedArgs ?? "reject") === "keep" && unknownNamedArgs.length > 0) {
+        meta.unknownNamedArgs = Object.fromEntries(unknownNamedArgs);
+      }
+      return buildResolvedRoute(instruction, definition, meta);
+    }
+    default:
+      return errorResult(instruction.raw, "unknown", void 0, `Unsupported route mode "${String(instruction.mode)}".`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANCHOR_ERROR_CODES,
+  ANCHOR_PATH_PREFIX,
+  ANCHOR_SEPARATOR,
+  ARG_SEPARATOR,
+  AnchorRouteError,
+  DOT_SEPARATOR,
+  RESERVED_ANCHOR_CHARACTERS,
+  SAFE_LITERAL_CHARACTER,
+  buildDotAnchor,
+  buildIntentAnchor,
+  buildPageAnchor,
+  buildParamAnchor,
+  createDiagnostic,
+  decodeAnchorKey,
+  decodeAnchorToken,
+  escapeAnchorKey,
+  escapeAnchorValue,
+  isAnchorRoute,
+  isAnchorRouteError,
+  isHexDigit,
+  isReservedAnchorCharacter,
+  normalizeAnchor,
+  parseAnchor,
+  resolveAnchor,
+  serializeAnchor,
+  validateAnchor,
+  validateEncodedToken
+});
+//# sourceMappingURL=index.js.map