{"_id":"@domglyph/ai-contract","_rev":"2-73d21eb255bacf008b8b51e4a09a2a32","name":"@domglyph/ai-contract","dist-tags":{"latest":"2.1.0"},"versions":{"2.0.0":{"name":"@domglyph/ai-contract","version":"2.0.0","_id":"@domglyph/ai-contract@2.0.0","maintainers":[{"name":"nishchya7pixels","email":"llcortex.ai@gmail.com"}],"dist":{"shasum":"bc221dc3e4b9a282ab984e89c214b995b2b086d5","tarball":"https://registry.npmjs.org/@domglyph/ai-contract/-/ai-contract-2.0.0.tgz","fileCount":5,"integrity":"sha512-TvnK+ZWNFQ5cWzS4ChbZ6BQaSG30aQ8pBA95OfKnUtX6FK2c+7Ywg3tgahbqvJvFt4baJMdLn52TB/rJi6LFAw==","signatures":[{"sig":"MEQCIGO/rHlNjtxP9aWTbGknvWfAk6L/GwqfBKftLxSTt3cwAiBUrhSZO+JKWirfjyGeQiw4oMsJRdMoEpH+L7O/P/268Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25749},"main":"./dist/index.js","type":"module","_from":"file:domglyph-ai-contract-2.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsup src/index.ts --format esm --dts --watch","lint":"eslint src --ext .ts","test":"vitest run --passWithNoTests","build":"tsup src/index.ts --format esm --dts --clean","typecheck":"tsc -b"},"_npmUser":{"name":"nishchya7pixels","email":"llcortex.ai@gmail.com"},"_resolved":"/private/var/folders/bb/st1qyn7d7ydd8__0z4mfw0480000gn/T/6fedf0256a1c9d6f38cbe0d0ff9f2d26/domglyph-ai-contract-2.0.0.tgz","_integrity":"sha512-TvnK+ZWNFQ5cWzS4ChbZ6BQaSG30aQ8pBA95OfKnUtX6FK2c+7Ywg3tgahbqvJvFt4baJMdLn52TB/rJi6LFAw==","_npmVersion":"11.8.0","description":"> **DOMglyph is now DOMglyph.** This package (`@domglyph/ai-contract`) is no longer maintained. All future updates are published under [`@domglyph/ai-contract`](https://www.npmjs.com/package/@domglyph/ai-contract). Please migrate to the new package.","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1"},"_npmOperationalInternal":{"tmp":"tmp/ai-contract_2.0.0_1775415711217_0.7361057008645417","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@domglyph/ai-contract","version":"2.1.0","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"devDependencies":{"tsup":"^8.5.1"},"scripts":{"build":"tsup src/index.ts --format esm --dts --clean","dev":"tsup src/index.ts --format esm --dts --watch","lint":"eslint src --ext .ts","test":"vitest run --passWithNoTests","typecheck":"tsc -b"},"_id":"@domglyph/ai-contract@2.1.0","description":"> **DOMglyph is now DOMglyph.** This package (`@domglyph/ai-contract`) is no longer maintained. All future updates are published under [`@domglyph/ai-contract`](https://www.npmjs.com/package/@domglyph/ai-contract). Please migrate to the new package.","_integrity":"sha512-1rw1x+1t/EQQ0PUHiTOmQx/IhohY05/x9fEYWqbEd6ZTE7MvtZsdfv3iusT/2Qz8SxQNHOF/RRxXjlQoLX4Nvw==","_resolved":"/private/var/folders/bb/st1qyn7d7ydd8__0z4mfw0480000gn/T/80dea5641365e77ed9f805b9211b1f0b/domglyph-ai-contract-2.1.0.tgz","_from":"file:domglyph-ai-contract-2.1.0.tgz","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-1rw1x+1t/EQQ0PUHiTOmQx/IhohY05/x9fEYWqbEd6ZTE7MvtZsdfv3iusT/2Qz8SxQNHOF/RRxXjlQoLX4Nvw==","shasum":"b252fdc168f2bd320eccf0b0029ecd0c9026395d","tarball":"https://registry.npmjs.org/@domglyph/ai-contract/-/ai-contract-2.1.0.tgz","fileCount":5,"unpackedSize":25749,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCdS1F3k/XRvMpONp5ywMBDn4Og1bxWazenwqDw3gCbwgIhALTKXCHKWH5SctQuKp1W6dijvWiA3Deq72YdDS19tz2Y"}]},"_npmUser":{"name":"nishchya7pixels","email":"llcortex.ai@gmail.com"},"directories":{},"maintainers":[{"name":"nishchya7pixels","email":"llcortex.ai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-contract_2.1.0_1775416539781_0.565992532665623"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-05T19:01:51.129Z","modified":"2026-04-05T19:15:40.052Z","2.0.0":"2026-04-05T19:01:51.374Z","2.1.0":"2026-04-05T19:15:39.932Z"},"description":"> **DOMglyph is now DOMglyph.** This package (`@domglyph/ai-contract`) is no longer maintained. All future updates are published under [`@domglyph/ai-contract`](https://www.npmjs.com/package/@domglyph/ai-contract). Please migrate to the new package.","maintainers":[{"name":"nishchya7pixels","email":"llcortex.ai@gmail.com"}],"readme":"> **DOMglyph is now DOMglyph.** This package (`@domglyph/ai-contract`) is no longer maintained. All future updates are published under [`@domglyph/ai-contract`](https://www.npmjs.com/package/@domglyph/ai-contract). Please migrate to the new package.\n\n---\n\n# @domglyph/ai-contract\n\n[![npm version](https://img.shields.io/npm/v/@domglyph/ai-contract?color=0ea5e9)](https://www.npmjs.com/package/@domglyph/ai-contract)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)\n\nThe machine-readable interface specification for DOMglyph (now DOMglyph).\n\n---\n\n## Overview\n\n`@domglyph/ai-contract` is the foundation of the DOMglyph system. It defines:\n\n- The complete `data-ai-*` attribute specification as string constants\n- TypeScript types for every role, state, event, and attribute map\n- Runtime validation utilities (`validateAIAttributes`, `extractAIAttributes`)\n- Event type definitions for the DOMglyph event log\n\nAll other DOMglyph packages depend on this package as their source of truth. It has no runtime dependencies and is safe to use in any environment — browser, Node.js, or test runner.\n\n---\n\n## Installation\n\n```bash\nnpm install @domglyph/ai-contract\n```\n\n---\n\n## The Attributes\n\n| Attribute | Description |\n|---|---|\n| `data-ai-id` | Stable unique identifier for the element. Used by agents to target a specific element across renders. |\n| `data-ai-role` | The semantic role of the element. One of the 9 defined roles (see below). |\n| `data-ai-action` | The verb-noun action name for action elements (e.g. `save-profile`, `delete-order`). |\n| `data-ai-state` | The current interactive state of the element. One of the 7 defined states (see below). |\n| `data-ai-screen` | The name of the screen or page this element belongs to. |\n| `data-ai-section` | The named section within a screen (e.g. `billing`, `profile`, `header`). |\n| `data-ai-entity` | The entity type this element represents or operates on (e.g. `user`, `order`, `product`). |\n| `data-ai-entity-id` | The specific instance ID of the entity (e.g. a user ID or order number). |\n| `data-ai-field-type` | The input type for field elements. One of: `text`, `email`, `password`, `number`, `select`, `checkbox`. |\n| `data-ai-required` | Whether a field is required. `\"true\"` or `\"false\"`. |\n| `data-ai-label` | A human-readable label for the element, used when the visible text is insufficient or absent. |\n\n---\n\n## Roles\n\nThe `data-ai-role` attribute identifies what kind of element this is:\n\n| Role | Description |\n|---|---|\n| `action` | An element that triggers an action when activated (button, link, etc.) |\n| `field` | A data entry element (input, select, textarea) |\n| `form` | A container grouping related fields and a submission action |\n| `table` | A data grid or tabular list of entities |\n| `modal` | A dialog or overlay requiring user attention |\n| `nav-item` | A navigation element (menu item, tab, breadcrumb link) |\n| `status` | A read-only element communicating system or entity status |\n| `screen` | The root container of the current screen or page |\n| `section` | A named sub-region of a screen |\n\n---\n\n## States\n\nThe `data-ai-state` attribute communicates the current interaction state:\n\n| State | Description |\n|---|---|\n| `idle` | Element is ready and interactive |\n| `loading` | Element is waiting for an async operation to complete |\n| `success` | The most recent operation completed successfully |\n| `error` | The most recent operation failed, or the element has a validation error |\n| `disabled` | Element is present but not currently interactive |\n| `expanded` | Element is in an open/expanded state (e.g. dropdown, accordion) |\n| `selected` | Element is in an active/selected state (e.g. tab, list item) |\n\n---\n\n## Events\n\nDOMglyph components emit structured events that are captured in the runtime event log.\n\n| Event | Description | Key Payload Fields |\n|---|---|---|\n| `action_triggered` | An action element was activated | `actionId`, `timestamp` |\n| `action_completed` | The action completed successfully | `actionId`, `result: 'success'`, `timestamp` |\n| `action_failed` | The action failed | `actionId`, `result: 'error'`, `message`, `timestamp` |\n| `form_submitted` | A form was submitted | `formId`, `timestamp` |\n| `field_updated` | A field value changed | `fieldId`, `timestamp` |\n\nTypeScript event types:\n\n```ts\ntype AIEventType =\n  | 'action_triggered'\n  | 'action_completed'\n  | 'action_failed'\n  | 'form_submitted'\n  | 'field_updated';\n\ninterface RuntimeEventLogEntry {\n  type: AIEventType;\n  actionId?: string;\n  formId?: string;\n  fieldId?: string;\n  result?: 'success' | 'error';\n  message?: string;\n  timestamp: number;\n}\n```\n\n---\n\n## Usage\n\n### Attribute constants\n\nImport attribute name constants to avoid magic strings:\n\n```ts\nimport {\n  DATA_AI_ROLE,\n  DATA_AI_STATE,\n  DATA_AI_ACTION,\n  DATA_AI_ID,\n  DATA_AI_ENTITY,\n  DATA_AI_ENTITY_ID,\n  DATA_AI_FIELD_TYPE,\n  DATA_AI_REQUIRED,\n  DATA_AI_SCREEN,\n  DATA_AI_SECTION,\n} from '@domglyph/ai-contract';\n\n// Use in React components:\n<button\n  {...{ [DATA_AI_ROLE]: 'action', [DATA_AI_ID]: 'save', [DATA_AI_STATE]: 'idle' }}\n>\n  Save\n</button>\n```\n\n### Validation\n\nValidate that a DOM element has a correct and complete AI contract:\n\n```ts\nimport { validateAIAttributes } from '@domglyph/ai-contract';\n\nconst result = validateAIAttributes(element);\n// {\n//   valid: boolean,\n//   errors: string[],\n//   attributes: AIAttributeMap\n// }\n\nif (!result.valid) {\n  console.error('AI contract violations:', result.errors);\n}\n```\n\n### Extracting attributes\n\nRead all `data-ai-*` attributes from a DOM element as a typed object:\n\n```ts\nimport { extractAIAttributes } from '@domglyph/ai-contract';\n\nconst attrs = extractAIAttributes(element);\n// {\n//   id: 'save-profile',\n//   role: 'action',\n//   action: 'save-profile',\n//   state: 'idle',\n//   screen: 'profile',\n//   section: 'contact-info',\n//   entity: null,\n//   entityId: null,\n//   fieldType: null,\n//   required: null\n// }\n```\n\n### TypeScript types\n\nKey types exported from this package:\n\n```ts\ntype AIRole =\n  | 'action'\n  | 'field'\n  | 'form'\n  | 'table'\n  | 'modal'\n  | 'nav-item'\n  | 'status'\n  | 'screen'\n  | 'section';\n\ntype AIState =\n  | 'idle'\n  | 'loading'\n  | 'success'\n  | 'error'\n  | 'disabled'\n  | 'expanded'\n  | 'selected';\n\ntype AIEvent =\n  | 'action_triggered'\n  | 'action_completed'\n  | 'action_failed'\n  | 'form_submitted'\n  | 'field_updated';\n\ninterface AIAttributeMap {\n  readonly id: string | null;\n  readonly role: AIRole | null;\n  readonly action: string | null;\n  readonly state: AIState | null;\n  readonly screen: string | null;\n  readonly section: string | null;\n  readonly entity: string | null;\n  readonly entityId: string | null;\n  readonly fieldType: string | null;\n  readonly required: boolean | null;\n}\n```\n\n---\n\n## Part of DOMglyph\n\n`@domglyph/ai-contract` is part of the [DOMglyph](../../README.md) design system.\n\n- [Main repository](../../README.md)\n- [Documentation](http://localhost:3001/docs/ai-contract)\n- [Contributing](../../CONTRIBUTING.md)\n\n---\n\n## ☕ Support\n\nIf you find DOMglyph useful, you can support the project:\n\n👉 https://buymeacoffee.com/nishchya\n\nIt helps keep the project alive and growing.\n","readmeFilename":"README.md"}