@uicontract/namer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UIC Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @uicontract/namer
+
+Naming engine that assigns hierarchical agent IDs to UI elements.
+
+## Install
+
+```bash
+npm install @uicontract/namer
+```
+
+## Usage
+
+```typescript
+import { assignNames } from '@uicontract/namer';
+import type { RawElement } from '@uicontract/core';
+
+const rawElements: RawElement[] = [
+  /* output from a parser */
+];
+
+const named = await assignNames(rawElements, {
+  projectRoot: '/path/to/my-app',
+});
+
+// Each element now has a stable, hierarchical agentId:
+// "settings.billing.pause-subscription.button"
+console.log(named[0].agentId);
+```
+
+## API
+
+- **`assignNames(elements, options)`**: Takes `RawElement[]` produced by a parser and returns `NamedElement[]`, each with a stable `agentId` in `route.component.element-name.type` dot-separated format.
+
+ID format: `<route>.<component>.<label>.<type>`
+
+Examples:
+- `settings.billing.pause-subscription.button`
+- `login.login-form.email.input`
+- `nav.header.sign-out.link`
+
+The namer is deterministic: the same element always receives the same ID across runs. It does not read source files or write anything to disk.
+
+## Part of UIC
+
+This package is part of [UIC (UI Contracts)](https://github.com/sherifkozman/uicontract) — making web app UIs machine-readable.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/ai-namer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AI-assisted naming engine (stub).
+ *
+ * TODO: Connect to an AI provider (e.g., OpenAI, Anthropic) to generate
+ * context-aware, human-friendly agent IDs. The AI namer should receive
+ * the full element context (surrounding code, component hierarchy, route
+ * structure) and produce a naming suggestion that is validated against
+ * the agent ID pattern before use. When the AI namer returns null or
+ * fails, the deterministic namer is used as a fallback.
+ */
+import type { RawElement } from '@uicontract/core';
+/** Options for the AI naming provider. */
+export interface AiNamerOptions {
+    /** Timeout in milliseconds for the AI provider call. */
+    timeout?: number;
+    /** AI provider identifier (e.g., "openai", "anthropic"). */
+    provider?: string;
+}
+/**
+ * Attempt to assign an AI-generated agent ID to a RawElement.
+ *
+ * Currently a stub that always returns null, causing the caller
+ * to fall back to deterministic naming.
+ *
+ * @param _element - The raw element to name.
+ * @param _options - AI provider options.
+ * @returns null (stub — AI naming not yet implemented).
+ */
+export declare function assignAiName(_element: RawElement, _options?: AiNamerOptions): Promise<string | null>;
+//# sourceMappingURL=ai-namer.d.ts.map

package/dist/ai-namer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-namer.d.ts","sourceRoot":"","sources":["../src/ai-namer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,UAAU,EACpB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB"}

package/dist/ai-namer.js

@@ -0,0 +1,29 @@
+/**
+ * AI-assisted naming engine (stub).
+ *
+ * TODO: Connect to an AI provider (e.g., OpenAI, Anthropic) to generate
+ * context-aware, human-friendly agent IDs. The AI namer should receive
+ * the full element context (surrounding code, component hierarchy, route
+ * structure) and produce a naming suggestion that is validated against
+ * the agent ID pattern before use. When the AI namer returns null or
+ * fails, the deterministic namer is used as a fallback.
+ */
+/**
+ * Attempt to assign an AI-generated agent ID to a RawElement.
+ *
+ * Currently a stub that always returns null, causing the caller
+ * to fall back to deterministic naming.
+ *
+ * @param _element - The raw element to name.
+ * @param _options - AI provider options.
+ * @returns null (stub — AI naming not yet implemented).
+ */
+export async function assignAiName(_element, _options) {
+    // TODO: Implement AI naming. This function should:
+    // 1. Serialize the element context into a prompt
+    // 2. Call the configured AI provider
+    // 3. Validate the response matches ^[a-z][a-z0-9.-]*$
+    // 4. Return the validated name, or null on failure/timeout
+    return null;
+}
+//# sourceMappingURL=ai-namer.js.map

package/dist/ai-namer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-namer.js","sourceRoot":"","sources":["../src/ai-namer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAoB,EACpB,QAAyB;IAEzB,mDAAmD;IACnD,iDAAiD;IACjD,qCAAqC;IACrC,sDAAsD;IACtD,2DAA2D;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/deduplicator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ID collision resolution for named elements.
+ *
+ * Detects duplicate agentIds and appends numeric suffixes (.0, .1, .2)
+ * to ALL duplicates. Duplicates are ordered by line number for stability.
+ */
+import type { NamedElement } from '@uicontract/core';
+/**
+ * Deduplicate named elements by appending numeric suffixes to collisions.
+ *
+ * When two or more elements share the same agentId, ALL of them receive
+ * a numeric suffix (.0, .1, .2, ...) ordered by line number (ascending).
+ *
+ * Elements with unique IDs are returned unchanged.
+ *
+ * @param elements - Array of named elements, potentially with duplicate IDs.
+ * @returns New array with unique agentIds. Original array is not mutated.
+ */
+export declare function deduplicateNames(elements: NamedElement[]): NamedElement[];
+//# sourceMappingURL=deduplicator.d.ts.map

package/dist/deduplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplicator.d.ts","sourceRoot":"","sources":["../src/deduplicator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAyCzE"}

package/dist/deduplicator.js

@@ -0,0 +1,60 @@
+/**
+ * ID collision resolution for named elements.
+ *
+ * Detects duplicate agentIds and appends numeric suffixes (.0, .1, .2)
+ * to ALL duplicates. Duplicates are ordered by line number for stability.
+ */
+/**
+ * Deduplicate named elements by appending numeric suffixes to collisions.
+ *
+ * When two or more elements share the same agentId, ALL of them receive
+ * a numeric suffix (.0, .1, .2, ...) ordered by line number (ascending).
+ *
+ * Elements with unique IDs are returned unchanged.
+ *
+ * @param elements - Array of named elements, potentially with duplicate IDs.
+ * @returns New array with unique agentIds. Original array is not mutated.
+ */
+export function deduplicateNames(elements) {
+    // Group element indices by agentId
+    const idGroups = new Map();
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (el === undefined)
+            continue;
+        const existing = idGroups.get(el.agentId);
+        if (existing !== undefined) {
+            existing.push(i);
+        }
+        else {
+            idGroups.set(el.agentId, [i]);
+        }
+    }
+    // Create a new array with resolved IDs
+    const result = elements.map((el) => ({ ...el }));
+    for (const indices of idGroups.values()) {
+        // Skip groups with no duplicates
+        if (indices.length <= 1)
+            continue;
+        // Sort duplicate indices by line number for stable ordering
+        const sortedIndices = [...indices].sort((a, b) => {
+            const elA = elements[a];
+            const elB = elements[b];
+            if (elA === undefined || elB === undefined)
+                return 0;
+            return elA.line - elB.line;
+        });
+        // Assign numeric suffixes
+        for (let suffixIdx = 0; suffixIdx < sortedIndices.length; suffixIdx++) {
+            const elementIndex = sortedIndices[suffixIdx];
+            if (elementIndex === undefined)
+                continue;
+            const el = result[elementIndex];
+            if (el === undefined)
+                continue;
+            el.agentId = `${el.agentId}.${suffixIdx}`;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=deduplicator.js.map

package/dist/deduplicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplicator.js","sourceRoot":"","sources":["../src/deduplicator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAwB;IACvD,mCAAmC;IACnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAC/B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,uCAAuC;IACvC,MAAM,MAAM,GAAmB,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAEjE,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,iCAAiC;QACjC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;YAAE,SAAS;QAElC,4DAA4D;QAC5D,MAAM,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,CAAC,CAAC;YACrD,OAAO,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QAC7B,CAAC,CAAC,CAAC;QAEH,0BAA0B;QAC1B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;YACtE,MAAM,YAAY,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;YAC9C,IAAI,YAAY,KAAK,SAAS;gBAAE,SAAS;YACzC,MAAM,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,EAAE,KAAK,SAAS;gBAAE,SAAS;YAC/B,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/deterministic-namer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rule-based deterministic naming engine.
+ *
+ * Assigns agentIds to RawElements using a priority-based strategy that
+ * combines route, label, handler, component name, and element type.
+ */
+import type { RawElement } from '@uicontract/core';
+/**
+ * Assign a deterministic agent ID to a RawElement.
+ *
+ * Priority order:
+ * 1. Route + label + type
+ * 2. Route + handler + type
+ * 3. Component + label + type
+ * 4. Component + handler + type
+ * 5. Fallback: component (or "unknown") + type + line
+ */
+export declare function assignDeterministicName(element: RawElement): string;
+//# sourceMappingURL=deterministic-namer.d.ts.map

package/dist/deterministic-namer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic-namer.d.ts","sourceRoot":"","sources":["../src/deterministic-namer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAsCnD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CA0CnE"}

package/dist/deterministic-namer.js

@@ -0,0 +1,77 @@
+/**
+ * Rule-based deterministic naming engine.
+ *
+ * Assigns agentIds to RawElements using a priority-based strategy that
+ * combines route, label, handler, component name, and element type.
+ */
+import { routeToSegments, labelToSegment, handlerToSegment, componentToSegment, } from './naming-rules.js';
+/** Agent ID validation pattern */
+const AGENT_ID_PATTERN = /^[a-z][a-z0-9.-]*$/;
+/**
+ * Join non-empty segments with dots and append the element type.
+ */
+function buildId(segments, type) {
+    const parts = [...segments, type].filter((s) => s.length > 0);
+    return parts.join('.');
+}
+/**
+ * Ensure an agentId matches the required pattern.
+ *
+ * If the id doesn't start with a letter, prefix with "el".
+ * If the id is empty, return "unknown".
+ */
+function ensureValid(id) {
+    if (id.length === 0)
+        return 'unknown';
+    if (AGENT_ID_PATTERN.test(id))
+        return id;
+    // Strip any remaining invalid characters
+    let cleaned = id.replace(/[^a-z0-9.-]/g, '');
+    // Ensure starts with a letter
+    cleaned = cleaned.replace(/^[^a-z]+/, '');
+    if (cleaned.length === 0)
+        return 'unknown';
+    return cleaned;
+}
+/**
+ * Assign a deterministic agent ID to a RawElement.
+ *
+ * Priority order:
+ * 1. Route + label + type
+ * 2. Route + handler + type
+ * 3. Component + label + type
+ * 4. Component + handler + type
+ * 5. Fallback: component (or "unknown") + type + line
+ */
+export function assignDeterministicName(element) {
+    const routeSegments = element.route !== null ? routeToSegments(element.route) : [];
+    const hasRoute = routeSegments.length > 0;
+    const labelSeg = element.label !== null ? labelToSegment(element.label) : '';
+    const hasLabel = labelSeg.length > 0;
+    const handlerSeg = element.handler !== null ? handlerToSegment(element.handler) : '';
+    const hasHandler = handlerSeg.length > 0;
+    const componentSeg = element.componentName !== null
+        ? componentToSegment(element.componentName)
+        : '';
+    const hasComponent = componentSeg.length > 0;
+    // Priority 1: route + label + type
+    if (hasRoute && hasLabel) {
+        return ensureValid(buildId([...routeSegments, labelSeg], element.type));
+    }
+    // Priority 2: route + handler + type
+    if (hasRoute && hasHandler) {
+        return ensureValid(buildId([...routeSegments, handlerSeg], element.type));
+    }
+    // Priority 3: component + label + type
+    if (hasComponent && hasLabel) {
+        return ensureValid(buildId([componentSeg, labelSeg], element.type));
+    }
+    // Priority 4: component + handler + type
+    if (hasComponent && hasHandler) {
+        return ensureValid(buildId([componentSeg, handlerSeg], element.type));
+    }
+    // Priority 5: fallback — component (or "unknown") + type + line
+    const base = hasComponent ? componentSeg : 'unknown';
+    return ensureValid(`${base}.${element.type}.${element.line}`);
+}
+//# sourceMappingURL=deterministic-namer.js.map

package/dist/deterministic-namer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic-namer.js","sourceRoot":"","sources":["../src/deterministic-namer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @uicontract/namer — naming engine for UIC elements.
+ *
+ * Takes RawElements discovered by a parser and assigns stable,
+ * hierarchical agentIds using deterministic rules (with an optional
+ * AI-assisted mode for future use).
+ */
+import type { RawElement, NamedElement } from '@uicontract/core';
+/** Options for the naming engine. */
+export interface NamerOptions {
+    /** Enable AI-assisted naming (falls back to deterministic if AI returns null). */
+    ai?: boolean;
+    /** Timeout in milliseconds for AI naming calls. */
+    aiTimeout?: number;
+}
+/**
+ * Name a list of raw elements, producing NamedElements with unique agentIds.
+ *
+ * 1. Each element is named via the deterministic namer (AI stub returns null).
+ * 2. Duplicate IDs are resolved with numeric suffixes.
+ *
+ * @param elements - Raw elements from a parser's discovery phase.
+ * @param options - Naming options (AI mode is stubbed for now).
+ * @returns Array of NamedElements with unique agentIds.
+ */
+export declare function nameElements(elements: ReadonlyArray<RawElement>, options?: NamerOptions): NamedElement[];
+export { sanitizeSegment, camelToKebab, routeToSegments, labelToSegment, handlerToSegment, componentToSegment, } from './naming-rules.js';
+export { assignDeterministicName } from './deterministic-namer.js';
+export { deduplicateNames } from './deduplicator.js';
+export { assignAiName } from './ai-namer.js';
+export type { AiNamerOptions } from './ai-namer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKjE,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,EACnC,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,EAAE,CA0BhB;AAGD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,48 @@
+/**
+ * @uicontract/namer — naming engine for UIC elements.
+ *
+ * Takes RawElements discovered by a parser and assigns stable,
+ * hierarchical agentIds using deterministic rules (with an optional
+ * AI-assisted mode for future use).
+ */
+import { assignDeterministicName } from './deterministic-namer.js';
+import { deduplicateNames } from './deduplicator.js';
+import { assignAiName } from './ai-namer.js';
+/**
+ * Name a list of raw elements, producing NamedElements with unique agentIds.
+ *
+ * 1. Each element is named via the deterministic namer (AI stub returns null).
+ * 2. Duplicate IDs are resolved with numeric suffixes.
+ *
+ * @param elements - Raw elements from a parser's discovery phase.
+ * @param options - Naming options (AI mode is stubbed for now).
+ * @returns Array of NamedElements with unique agentIds.
+ */
+export function nameElements(elements, options) {
+    const useAi = options?.ai ?? false;
+    const aiTimeout = options?.aiTimeout;
+    // Phase 1: assign names
+    const named = elements.map((element) => {
+        let agentId = null;
+        // Attempt AI naming if enabled (currently a stub that returns null)
+        if (useAi) {
+            // AI naming is async but we handle it synchronously here since
+            // the stub always returns null. When real AI is connected, this
+            // function signature should become async.
+            void assignAiName(element, { timeout: aiTimeout });
+        }
+        // Deterministic fallback (always used until AI is implemented)
+        if (agentId === null) {
+            agentId = assignDeterministicName(element);
+        }
+        return { ...element, agentId };
+    });
+    // Phase 2: deduplicate
+    return deduplicateNames(named);
+}
+// Re-export individual modules for direct access and testing
+export { sanitizeSegment, camelToKebab, routeToSegments, labelToSegment, handlerToSegment, componentToSegment, } from './naming-rules.js';
+export { assignDeterministicName } from './deterministic-namer.js';
+export { deduplicateNames } from './deduplicator.js';
+export { assignAiName } from './ai-namer.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAU7C;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAmC,EACnC,OAAsB;IAEtB,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,IAAI,KAAK,CAAC;IACnC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;IAErC,wBAAwB;IACxB,MAAM,KAAK,GAAmB,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACrD,IAAI,OAAO,GAAkB,IAAI,CAAC;QAElC,oEAAoE;QACpE,IAAI,KAAK,EAAE,CAAC;YACV,+DAA+D;YAC/D,gEAAgE;YAChE,0CAA0C;YAC1C,KAAK,YAAY,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,+DAA+D;QAC/D,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,uBAAuB;IACvB,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/naming-rules.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Character sanitization and naming rules for agent ID segments.
+ *
+ * Agent IDs must match: ^[a-z][a-z0-9.-]*$
+ * Each segment is a dot-separated part of the ID.
+ */
+/**
+ * Convert camelCase or PascalCase text to kebab-case.
+ *
+ * Handles consecutive uppercase letters (acronyms) by treating them as a
+ * single group followed by the next lowercase run.
+ * e.g. "MyHTTPClient" -> "my-http-client"
+ */
+export declare function camelToKebab(text: string): string;
+/**
+ * Sanitize a text string into a valid agent ID segment.
+ *
+ * - Lowercases
+ * - Replaces spaces, underscores, and camelCase boundaries with hyphens
+ * - Removes special characters (keeps letters, digits, hyphens)
+ * - Collapses consecutive hyphens
+ * - Trims leading and trailing hyphens
+ * - Strips leading digits so the segment starts with a letter
+ */
+export declare function sanitizeSegment(text: string): string;
+/**
+ * Split a route path into sanitized segments.
+ *
+ * e.g. "/settings/billing" -> ["settings", "billing"]
+ */
+export declare function routeToSegments(route: string): string[];
+/**
+ * Convert a label string into a sanitized segment.
+ *
+ * e.g. "Pause subscription" -> "pause-subscription"
+ */
+export declare function labelToSegment(label: string): string;
+/**
+ * Convert an event handler name into a sanitized segment.
+ *
+ * Strips common prefixes ("handle", "on") before converting.
+ * e.g. "handlePauseSubscription" -> "pause-subscription"
+ * e.g. "onClick" -> "click"
+ */
+export declare function handlerToSegment(handler: string): string;
+/**
+ * Convert a component name (PascalCase/camelCase) into a sanitized segment.
+ *
+ * e.g. "BillingSettings" -> "billing-settings"
+ */
+export declare function componentToSegment(componentName: string): string;
+//# sourceMappingURL=naming-rules.d.ts.map

package/dist/naming-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming-rules.d.ts","sourceRoot":"","sources":["../src/naming-rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAyBpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/naming-rules.js

@@ -0,0 +1,101 @@
+/**
+ * Character sanitization and naming rules for agent ID segments.
+ *
+ * Agent IDs must match: ^[a-z][a-z0-9.-]*$
+ * Each segment is a dot-separated part of the ID.
+ */
+/**
+ * Convert camelCase or PascalCase text to kebab-case.
+ *
+ * Handles consecutive uppercase letters (acronyms) by treating them as a
+ * single group followed by the next lowercase run.
+ * e.g. "MyHTTPClient" -> "my-http-client"
+ */
+export function camelToKebab(text) {
+    if (text.length === 0)
+        return '';
+    // Insert hyphen between lowercase/digit and uppercase
+    let result = text.replace(/([a-z0-9])([A-Z])/g, '$1-$2');
+    // Insert hyphen between consecutive uppercase and uppercase+lowercase
+    result = result.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2');
+    return result.toLowerCase();
+}
+/**
+ * Sanitize a text string into a valid agent ID segment.
+ *
+ * - Lowercases
+ * - Replaces spaces, underscores, and camelCase boundaries with hyphens
+ * - Removes special characters (keeps letters, digits, hyphens)
+ * - Collapses consecutive hyphens
+ * - Trims leading and trailing hyphens
+ * - Strips leading digits so the segment starts with a letter
+ */
+export function sanitizeSegment(text) {
+    if (text.length === 0)
+        return '';
+    // First convert camelCase to kebab-case
+    let result = camelToKebab(text);
+    // Replace spaces and underscores with hyphens
+    result = result.replace(/[\s_]+/g, '-');
+    // Replace anything that isn't a lowercase letter, digit, or hyphen with a hyphen
+    result = result.replace(/[^a-z0-9-]+/g, '-');
+    // Collapse consecutive hyphens
+    result = result.replace(/-{2,}/g, '-');
+    // Trim leading and trailing hyphens
+    result = result.replace(/^-+|-+$/g, '');
+    // Strip leading digits so result starts with a letter
+    result = result.replace(/^[0-9]+/, '');
+    // Trim hyphens again after digit stripping
+    result = result.replace(/^-+/, '');
+    return result;
+}
+/**
+ * Split a route path into sanitized segments.
+ *
+ * e.g. "/settings/billing" -> ["settings", "billing"]
+ */
+export function routeToSegments(route) {
+    return route
+        .split('/')
+        .map((s) => sanitizeSegment(s))
+        .filter((s) => s.length > 0);
+}
+/**
+ * Convert a label string into a sanitized segment.
+ *
+ * e.g. "Pause subscription" -> "pause-subscription"
+ */
+export function labelToSegment(label) {
+    return sanitizeSegment(label);
+}
+/**
+ * Convert an event handler name into a sanitized segment.
+ *
+ * Strips common prefixes ("handle", "on") before converting.
+ * e.g. "handlePauseSubscription" -> "pause-subscription"
+ * e.g. "onClick" -> "click"
+ */
+export function handlerToSegment(handler) {
+    let stripped = handler;
+    // Strip "handle" prefix (case-sensitive, expect camelCase)
+    if (stripped.startsWith('handle') && stripped.length > 6) {
+        stripped = stripped.slice(6);
+        // Lowercase the first character of the remaining text
+        stripped = stripped.charAt(0).toLowerCase() + stripped.slice(1);
+    }
+    // Strip "on" prefix (case-sensitive)
+    else if (stripped.startsWith('on') && stripped.length > 2 && /[A-Z]/.test(stripped.charAt(2))) {
+        stripped = stripped.slice(2);
+        stripped = stripped.charAt(0).toLowerCase() + stripped.slice(1);
+    }
+    return sanitizeSegment(stripped);
+}
+/**
+ * Convert a component name (PascalCase/camelCase) into a sanitized segment.
+ *
+ * e.g. "BillingSettings" -> "billing-settings"
+ */
+export function componentToSegment(componentName) {
+    return sanitizeSegment(componentName);
+}
+//# sourceMappingURL=naming-rules.js.map

package/dist/naming-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming-rules.js","sourceRoot":"","sources":["../src/naming-rules.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@uicontract/namer",
+  "version": "0.1.0",
+  "description": "Naming engine that assigns hierarchical agent IDs to UI elements",
+  "type": "module",
+  "license": "MIT",
+  "author": "UIC Contributors",
+  "homepage": "https://github.com/sherifkozman/uicontract/tree/main/packages/namer",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sherifkozman/uicontract.git",
+    "directory": "packages/namer"
+  },
+  "bugs": {
+    "url": "https://github.com/sherifkozman/uicontract/issues"
+  },
+  "keywords": [
+    "uic",
+    "ui-contracts",
+    "namer",
+    "agent-id",
+    "naming-engine"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@uicontract/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  }
+}