@domglyph/runtime 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llcortex
+
+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,259 @@
+# @domglyph/runtime (formerly [@cortexui/runtime](https://www.npmjs.com/package/@cortexui/runtime))
+
+[![npm version](https://img.shields.io/npm/v/@domglyph/runtime?color=0ea5e9)](https://www.npmjs.com/package/@domglyph/runtime)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+
+The browser runtime that makes DOMglyph pages inspectable by AI agents.
+
+---
+
+## Overview
+
+`@domglyph/runtime` installs `window.__CORTEX_UI__` — a structured inspection API that AI agents use instead of scraping the DOM.
+
+Without this runtime, an AI agent visiting your page would need to traverse the DOM, parse CSS, infer intent from visible text, and guess at state. With this runtime, the agent calls a single function and gets back a typed, structured description of exactly what is on screen and what can be done.
+
+The runtime works by reading the `data-ai-*` attributes that DOMglyph components emit. It requires no separate data store, no backend, and no framework integration beyond a single `installDOMglyphRuntime()` call.
+
+---
+
+## Installation
+
+```bash
+npm install @domglyph/runtime
+```
+
+---
+
+## Setup
+
+### With React (recommended)
+
+Call `installDOMglyphRuntime` once in your application's entry point, before the app renders:
+
+```tsx
+import { installDOMglyphRuntime } from '@domglyph/runtime';
+
+// Install before rendering
+installDOMglyphRuntime(window);
+
+// Then render your app
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+### Verifying installation
+
+Open the browser console on any DOMglyph page and run:
+
+```js
+console.log(window.__CORTEX_UI__.getScreenContext());
+```
+
+If `__CORTEX_UI__` is defined and returns a context object, the runtime is installed correctly.
+
+---
+
+## API Reference
+
+### getScreenContext()
+
+Returns the screen-level context for the current page view. This is the first thing an agent should call to orient itself.
+
+```ts
+getScreenContext(): {
+  screen: string | null;      // value of data-ai-screen on the root element
+  entity: string | null;      // value of data-ai-entity on the screen root
+  entityId: string | null;    // value of data-ai-entity-id on the screen root
+  sections: string[];         // all data-ai-section values present on this screen
+}
+```
+
+Example output:
+
+```js
+window.__CORTEX_UI__.getScreenContext();
+// {
+//   screen: "order-detail",
+//   entity: "order",
+//   entityId: "ord-9142",
+//   sections: ["summary", "line-items", "shipping", "actions"]
+// }
+```
+
+---
+
+### getAvailableActions()
+
+Returns every element with `data-ai-role="action"` that is currently rendered and not in a `disabled` state. This tells the agent what it can do right now.
+
+```ts
+getAvailableActions(): Array<{
+  id: string;             // data-ai-id
+  action: string;         // data-ai-action
+  state: string;          // data-ai-state
+  section: string | null; // data-ai-section (if present)
+}>
+```
+
+Example output:
+
+```js
+window.__CORTEX_UI__.getAvailableActions();
+// [
+//   { id: "approve-order", action: "approve-order", state: "idle", section: "actions" },
+//   { id: "cancel-order",  action: "cancel-order",  state: "idle", section: "actions" },
+//   { id: "edit-shipping", action: "edit-shipping",  state: "idle", section: "shipping" }
+// ]
+```
+
+---
+
+### getFormSchema(formId)
+
+Returns the field schema for a form identified by its `data-ai-id`. Returns `null` if no matching form is found.
+
+```ts
+getFormSchema(formId: string): {
+  formId: string;
+  fields: Array<{
+    id: string;                  // data-ai-id of the field
+    fieldType: string;           // data-ai-field-type
+    required: boolean;           // data-ai-required
+    currentValue: string | null; // current input value
+    state: string;               // data-ai-state of the field
+  }>;
+} | null
+```
+
+Example output:
+
+```js
+window.__CORTEX_UI__.getFormSchema('edit-shipping-form');
+// {
+//   formId: "edit-shipping-form",
+//   fields: [
+//     { id: "shipping-name",    fieldType: "text",   required: true,  currentValue: "Jane Smith", state: "idle" },
+//     { id: "shipping-address", fieldType: "text",   required: true,  currentValue: "",           state: "error" },
+//     { id: "shipping-country", fieldType: "select", required: true,  currentValue: "US",         state: "idle" }
+//   ]
+// }
+```
+
+---
+
+### getVisibleEntities()
+
+Returns all elements carrying `data-ai-entity` that are currently in the viewport. Useful for understanding what data the user can see.
+
+```ts
+getVisibleEntities(): Array<{
+  entity: string;         // data-ai-entity
+  entityId: string | null; // data-ai-entity-id
+  section: string | null;  // data-ai-section
+}>
+```
+
+Example output:
+
+```js
+window.__CORTEX_UI__.getVisibleEntities();
+// [
+//   { entity: "order",   entityId: "ord-9142", section: "summary" },
+//   { entity: "product", entityId: "prd-001",  section: "line-items" },
+//   { entity: "product", entityId: "prd-007",  section: "line-items" }
+// ]
+```
+
+---
+
+### getRecentEvents()
+
+Returns a log of recent interaction events in chronological order. Use this to verify that an action completed, or to understand what has happened on screen since the last check.
+
+```ts
+getRecentEvents(): Array<{
+  type: 'action_triggered' | 'action_completed' | 'action_failed' | 'form_submitted' | 'field_updated';
+  actionId?: string;
+  formId?: string;
+  fieldId?: string;
+  result?: 'success' | 'error';
+  message?: string;
+  timestamp: number;
+}>
+```
+
+Example output:
+
+```js
+window.__CORTEX_UI__.getRecentEvents();
+// [
+//   { type: "action_triggered", actionId: "approve-order", timestamp: 1711900000000 },
+//   { type: "action_completed", actionId: "approve-order", result: "success", timestamp: 1711900000250 }
+// ]
+```
+
+---
+
+## Devtools
+
+In development, you can install the extended devtools runtime for additional inspection capabilities:
+
+```ts
+import { installDOMglyphDevtools } from '@domglyph/runtime';
+
+installDOMglyphDevtools(window);
+// window.__CORTEX_UI_DEVTOOLS__ is now available
+```
+
+The devtools runtime adds:
+
+- Full DOM node references in query results
+- Attribute validation warnings in the console
+- A mutation observer log showing when `data-ai-*` attributes change
+
+Do not install devtools in production builds.
+
+---
+
+## Using with AI Agents
+
+A typical agent interaction loop using the DOMglyph runtime:
+
+```js
+// Step 1: Orient — where am I and what entity am I looking at?
+const ctx = window.__CORTEX_UI__.getScreenContext();
+// { screen: "profile", entity: "user", entityId: "usr-42", sections: [...] }
+
+// Step 2: Survey — what actions can I take right now?
+const actions = window.__CORTEX_UI__.getAvailableActions();
+// [{ id: "save-profile", action: "save-profile", state: "idle", section: "contact" }]
+
+// Step 3: Act — trigger the desired action deterministically
+document.querySelector(`[data-ai-id="${actions[0].id}"]`).click();
+
+// Step 4: Verify — did it work?
+const events = window.__CORTEX_UI__.getRecentEvents();
+// [{ type: "action_completed", actionId: "save-profile", result: "success", ... }]
+```
+
+This pattern is stable across re-renders, redesigns, and component updates. As long as the component exports the same `data-ai-action`, the agent's code does not need to change.
+
+---
+
+## Part of DOMglyph
+
+`@domglyph/runtime` is part of the [DOMglyph](../../README.md) design system.
+
+- [Main repository](../../README.md)
+- [Documentation](http://localhost:3001/docs/runtime)
+- [Contributing](../../CONTRIBUTING.md)
+
+---
+
+## ☕ Support
+
+If you find DOMglyph useful, you can support the project:
+
+👉 https://buymeacoffee.com/nishchya
+
+It helps keep the project alive and growing.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { AIAction, AIEvent } from '@domglyph/ai-contract';
+
+interface ScreenContext {
+    readonly screenId?: string;
+    readonly sectionIds: readonly string[];
+    readonly url?: string;
+    readonly title?: string;
+    readonly visibleActionIds: readonly string[];
+    readonly visibleEntityTypes: readonly string[];
+}
+interface AvailableAction extends AIAction {
+    readonly elementId?: string;
+    readonly label?: string;
+    readonly role?: string;
+    readonly disabled: boolean;
+    readonly state: readonly string[];
+}
+interface FormFieldSchema {
+    readonly id: string;
+    readonly label?: string;
+    readonly fieldType?: string;
+    readonly required: boolean;
+    readonly state: readonly string[];
+    readonly placeholder?: string;
+}
+interface FormSchema {
+    readonly id: string;
+    readonly screenId?: string;
+    readonly sectionId?: string;
+    readonly fields: readonly FormFieldSchema[];
+    readonly submitActions: readonly AvailableAction[];
+}
+interface VisibleEntity {
+    readonly entity: string;
+    readonly entityId?: string;
+    readonly screenId?: string;
+    readonly sectionId?: string;
+    readonly text?: string;
+}
+interface RuntimeEventLogEntry {
+    readonly type: AIEvent | "mutation_observed" | "screen_context_changed";
+    readonly timestamp: number;
+    readonly targetId?: string;
+    readonly detail?: unknown;
+}
+interface RuntimeRegistry {
+    readonly prompt: string;
+    readonly components: readonly string[];
+}
+interface DOMglyphGlobalAPI {
+    getScreenContext(): ScreenContext;
+    getAvailableActions(): readonly AvailableAction[];
+    getFormSchema(formId: string): FormSchema | null;
+    getVisibleEntities(): readonly VisibleEntity[];
+    getRecentEvents(): readonly RuntimeEventLogEntry[];
+}
+interface DOMglyphDevtoolsAPI {
+    show(): void;
+    hide(): void;
+    toggle(): boolean;
+    destroy(): void;
+    isVisible(): boolean;
+}
+
+declare function installDOMglyphDevtools(targetWindow?: Window): DOMglyphDevtoolsAPI | null;
+
+declare class DOMglyphRuntime implements DOMglyphGlobalAPI {
+    private readonly win;
+    private readonly doc;
+    private readonly actionRegistry;
+    private readonly recentEvents;
+    private mutationObserver;
+    private lastScreenSignature;
+    constructor(win: Window, doc: Document);
+    getScreenContext(): ScreenContext;
+    getAvailableActions(): readonly AvailableAction[];
+    getFormSchema(formId: string): FormSchema | null;
+    getVisibleEntities(): readonly VisibleEntity[];
+    getRecentEvents(): readonly RuntimeEventLogEntry[];
+    private attachEventListeners;
+    private attachMutationObserver;
+    private logMutationMetadata;
+    private refreshActionRegistry;
+    private buildActionEntry;
+    private extractFieldSchema;
+    private getVisibleElements;
+    private buildScreenSignature;
+    private logEvent;
+}
+declare function installDOMglyphRuntime(targetWindow?: Window): DOMglyphGlobalAPI | null;
+
+declare const runtimeRegistry: RuntimeRegistry;
+declare const defaultRuntimeEvent: "action_triggered";
+declare const CORTEX_UI: DOMglyphGlobalAPI | null;
+declare const CORTEX_UI_DEVTOOLS: DOMglyphDevtoolsAPI | null;
+declare global {
+    interface Window {
+        CORTEX_UI?: DOMglyphGlobalAPI;
+        CORTEX_UI_DEVTOOLS?: DOMglyphDevtoolsAPI;
+    }
+}
+
+export { type AvailableAction, CORTEX_UI, CORTEX_UI_DEVTOOLS, type DOMglyphDevtoolsAPI, type DOMglyphGlobalAPI, DOMglyphRuntime, type FormFieldSchema, type FormSchema, type RuntimeEventLogEntry, type RuntimeRegistry, type ScreenContext, type VisibleEntity, defaultRuntimeEvent, installDOMglyphDevtools, installDOMglyphRuntime, runtimeRegistry };

package/dist/index.js

@@ -0,0 +1,629 @@
+// src/index.ts
+import { AIEvent as AIEvent2 } from "@domglyph/ai-contract";
+
+// src/devtools.ts
+import {
+  AI_ATTRIBUTE_NAMES,
+  DATA_AI_ACTION as DATA_AI_ACTION2,
+  DATA_AI_ID as DATA_AI_ID2,
+  DATA_AI_ROLE as DATA_AI_ROLE2,
+  DATA_AI_STATE as DATA_AI_STATE2,
+  extractAIAttributes as extractAIAttributes2
+} from "@domglyph/ai-contract";
+
+// src/runtime.ts
+import {
+  AIEvent,
+  AIRole,
+  DATA_AI_ACTION,
+  DATA_AI_ENTITY,
+  DATA_AI_ENTITY_ID,
+  DATA_AI_EVENT,
+  DATA_AI_FEEDBACK,
+  DATA_AI_FIELD_TYPE,
+  DATA_AI_ID,
+  DATA_AI_REQUIRED,
+  DATA_AI_RESULT,
+  DATA_AI_ROLE,
+  DATA_AI_SCREEN,
+  DATA_AI_SECTION,
+  DATA_AI_STATE,
+  DATA_AI_STATUS,
+  extractAIAttributes
+} from "@domglyph/ai-contract";
+var ACTION_SELECTOR = `[${DATA_AI_ACTION}]`;
+var EVENT_SELECTOR = `[${DATA_AI_EVENT}]`;
+var SCREEN_SELECTOR = `[${DATA_AI_SCREEN}]`;
+var SECTION_SELECTOR = `[${DATA_AI_SECTION}]`;
+var ENTITY_SELECTOR = `[${DATA_AI_ENTITY}]`;
+var FIELD_SELECTOR = `input, textarea, select, [${DATA_AI_ROLE}="${AIRole.FIELD}"]`;
+var FORM_SELECTOR = `form, [${DATA_AI_ROLE}="${AIRole.FORM}"]`;
+var MAX_EVENT_LOG = 100;
+var DOMglyphRuntime = class {
+  constructor(win, doc) {
+    this.win = win;
+    this.doc = doc;
+    this.refreshActionRegistry();
+    this.lastScreenSignature = this.buildScreenSignature();
+    this.attachEventListeners();
+    this.attachMutationObserver();
+  }
+  actionRegistry = /* @__PURE__ */ new Map();
+  recentEvents = [];
+  mutationObserver = null;
+  lastScreenSignature = "";
+  getScreenContext() {
+    const screenElement = this.getVisibleElements(SCREEN_SELECTOR)[0];
+    const sectionIds = unique(
+      this.getVisibleElements(SECTION_SELECTOR).map((element) => element.getAttribute(DATA_AI_SECTION) ?? void 0).filter(isDefined)
+    );
+    const visibleActionIds = this.getAvailableActions().map((action) => action.id);
+    const visibleEntityTypes = unique(
+      this.getVisibleEntities().map((entity) => entity.entity)
+    );
+    return {
+      screenId: screenElement?.getAttribute(DATA_AI_SCREEN) ?? void 0,
+      sectionIds,
+      title: this.doc.title || void 0,
+      url: this.win.location.href,
+      visibleActionIds,
+      visibleEntityTypes
+    };
+  }
+  getAvailableActions() {
+    this.refreshActionRegistry();
+    return Array.from(this.actionRegistry.values()).map(({ attributes, ...action }) => action);
+  }
+  getFormSchema(formId) {
+    const formElement = this.doc.getElementById(formId) ?? this.doc.querySelector(`${FORM_SELECTOR}[${DATA_AI_ID}="${cssEscape(formId)}"]`);
+    if (formElement === null) {
+      return null;
+    }
+    const formAttributes = extractAIAttributes(formElement);
+    const screenId = formElement.closest(SCREEN_SELECTOR)?.getAttribute(DATA_AI_SCREEN) ?? void 0;
+    const sectionId = formElement.closest(SECTION_SELECTOR)?.getAttribute(DATA_AI_SECTION) ?? void 0;
+    const fields = Array.from(formElement.querySelectorAll(FIELD_SELECTOR)).filter((element) => isVisible(element)).map((field) => this.extractFieldSchema(field)).filter(isDefined);
+    const submitActions = Array.from(formElement.querySelectorAll(ACTION_SELECTOR)).filter((element) => isVisible(element)).map((element) => this.buildActionEntry(element)).filter(isDefined).map(({ attributes, ...action }) => action);
+    return {
+      fields,
+      id: formAttributes[DATA_AI_ID] ?? formElement.id ?? formId,
+      screenId,
+      sectionId,
+      submitActions
+    };
+  }
+  getVisibleEntities() {
+    return this.getVisibleElements(ENTITY_SELECTOR).map((element) => {
+      const attributes = extractAIAttributes(element);
+      return {
+        entity: attributes[DATA_AI_ENTITY] ?? "unknown",
+        entityId: attributes[DATA_AI_ENTITY_ID],
+        screenId: element.closest(SCREEN_SELECTOR)?.getAttribute(DATA_AI_SCREEN) ?? void 0,
+        sectionId: element.closest(SECTION_SELECTOR)?.getAttribute(DATA_AI_SECTION) ?? void 0,
+        text: textPreview(element)
+      };
+    });
+  }
+  getRecentEvents() {
+    return [...this.recentEvents];
+  }
+  attachEventListeners() {
+    this.doc.addEventListener(
+      "click",
+      (event) => {
+        const target = event.target instanceof Element ? event.target.closest(ACTION_SELECTOR) : null;
+        if (target === null) {
+          return;
+        }
+        const action = this.buildActionEntry(target);
+        if (action !== null) {
+          this.logEvent(AIEvent.ACTION_TRIGGERED, action.id, {
+            action: action.name,
+            disabled: action.disabled
+          });
+        }
+      },
+      true
+    );
+    this.doc.addEventListener(
+      "input",
+      (event) => {
+        const target = event.target instanceof HTMLElement ? event.target.closest(FIELD_SELECTOR) : null;
+        if (target === null) {
+          return;
+        }
+        const attributes = extractAIAttributes(target);
+        this.logEvent(AIEvent.FIELD_UPDATED, attributes[DATA_AI_ID], {
+          fieldType: attributes[DATA_AI_FIELD_TYPE],
+          required: attributes[DATA_AI_REQUIRED]
+        });
+      },
+      true
+    );
+    this.doc.addEventListener(
+      "submit",
+      (event) => {
+        const target = event.target instanceof HTMLElement ? event.target.closest(FORM_SELECTOR) : null;
+        if (target === null) {
+          return;
+        }
+        const attributes = extractAIAttributes(target);
+        const formId = attributes[DATA_AI_ID] ?? (target.id || void 0);
+        this.logEvent(AIEvent.FORM_SUBMITTED, formId);
+      },
+      true
+    );
+  }
+  attachMutationObserver() {
+    if (typeof MutationObserver === "undefined") {
+      return;
+    }
+    this.mutationObserver = new MutationObserver((mutations) => {
+      let shouldRefreshActions = false;
+      let shouldCheckScreen = false;
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes" && mutation.target instanceof HTMLElement) {
+          shouldRefreshActions = shouldRefreshActions || mutation.target.matches(ACTION_SELECTOR);
+          shouldCheckScreen = shouldCheckScreen || mutation.target.hasAttribute(DATA_AI_SCREEN) || mutation.target.hasAttribute(DATA_AI_SECTION);
+          this.logMutationMetadata(mutation.target);
+        }
+        if (mutation.type === "childList") {
+          shouldRefreshActions = true;
+          shouldCheckScreen = true;
+          mutation.addedNodes.forEach((node) => {
+            if (node instanceof HTMLElement) {
+              this.logMutationMetadata(node);
+            }
+          });
+        }
+      }
+      if (shouldRefreshActions) {
+        this.refreshActionRegistry();
+      }
+      if (shouldCheckScreen) {
+        const nextSignature = this.buildScreenSignature();
+        if (nextSignature !== this.lastScreenSignature) {
+          this.lastScreenSignature = nextSignature;
+          this.logEvent("screen_context_changed", void 0, this.getScreenContext());
+        }
+      }
+    });
+    const root = this.doc.body ?? this.doc.documentElement;
+    this.mutationObserver.observe(root, {
+      attributes: true,
+      attributeFilter: [
+        DATA_AI_ACTION,
+        DATA_AI_EVENT,
+        DATA_AI_ID,
+        DATA_AI_SCREEN,
+        DATA_AI_SECTION,
+        DATA_AI_STATE,
+        DATA_AI_STATUS
+      ],
+      childList: true,
+      subtree: true
+    });
+  }
+  logMutationMetadata(root) {
+    const eventNodes = [
+      ...root.matches(EVENT_SELECTOR) ? [root] : [],
+      ...Array.from(root.querySelectorAll(EVENT_SELECTOR))
+    ];
+    for (const node of eventNodes) {
+      const attributes = extractAIAttributes(node);
+      const eventType = attributes[DATA_AI_EVENT];
+      if (eventType !== void 0) {
+        this.logEvent(eventType, attributes[DATA_AI_ID], {
+          feedback: attributes[DATA_AI_FEEDBACK],
+          status: attributes[DATA_AI_STATUS]
+        });
+      }
+    }
+    if (eventNodes.length > 0) {
+      this.logEvent("mutation_observed", void 0, {
+        nodes: eventNodes.length
+      });
+    }
+  }
+  refreshActionRegistry() {
+    this.actionRegistry.clear();
+    for (const element of this.getVisibleElements(ACTION_SELECTOR)) {
+      const action = this.buildActionEntry(element);
+      if (action !== null) {
+        this.actionRegistry.set(action.id, action);
+      }
+    }
+  }
+  buildActionEntry(element) {
+    const attributes = extractAIAttributes(element);
+    const actionId = attributes[DATA_AI_ACTION];
+    if (actionId === void 0) {
+      return null;
+    }
+    const state = parseStates(attributes[DATA_AI_STATE]);
+    const disabled = state.includes("disabled") || element.matches(":disabled") || element.getAttribute("aria-disabled") === "true";
+    return {
+      attributes,
+      disabled,
+      elementId: attributes[DATA_AI_ID],
+      expectedOutcome: attributes[DATA_AI_RESULT],
+      id: actionId,
+      label: textPreview(element),
+      name: actionId,
+      role: attributes[DATA_AI_ROLE],
+      state,
+      target: describeTarget(element)
+    };
+  }
+  extractFieldSchema(field) {
+    const attributes = extractAIAttributes(field);
+    const fieldId = attributes[DATA_AI_ID] ?? field.getAttribute("id") ?? void 0;
+    if (fieldId === void 0) {
+      return null;
+    }
+    const htmlField = field;
+    return {
+      fieldType: attributes[DATA_AI_FIELD_TYPE] ?? ("type" in htmlField ? htmlField.type : void 0),
+      id: fieldId,
+      label: findLabelText(field),
+      placeholder: "placeholder" in htmlField ? htmlField.placeholder || void 0 : void 0,
+      required: attributes[DATA_AI_REQUIRED] === "true" || "required" in htmlField && Boolean(htmlField.required),
+      state: parseStates(attributes[DATA_AI_STATE])
+    };
+  }
+  getVisibleElements(selector) {
+    return Array.from(this.doc.querySelectorAll(selector)).filter((element) => isVisible(element));
+  }
+  buildScreenSignature() {
+    const context = this.getScreenContext();
+    return JSON.stringify(context);
+  }
+  logEvent(type, targetId, detail) {
+    this.recentEvents.unshift({
+      detail,
+      targetId,
+      timestamp: Date.now(),
+      type
+    });
+    if (this.recentEvents.length > MAX_EVENT_LOG) {
+      this.recentEvents.length = MAX_EVENT_LOG;
+    }
+  }
+};
+function installDOMglyphRuntime(targetWindow = window) {
+  if (typeof targetWindow === "undefined" || targetWindow.document === void 0) {
+    return null;
+  }
+  if (targetWindow.CORTEX_UI !== void 0) {
+    return targetWindow.CORTEX_UI;
+  }
+  const runtime = new DOMglyphRuntime(targetWindow, targetWindow.document);
+  targetWindow.CORTEX_UI = runtime;
+  return runtime;
+}
+function parseStates(value) {
+  return value?.split(",").map((state) => state.trim()).filter(Boolean) ?? [];
+}
+function describeTarget(element) {
+  const href = element.getAttribute("href");
+  if (href) {
+    return href;
+  }
+  const target = element.getAttribute("aria-controls");
+  if (target) {
+    return target;
+  }
+  return element.getAttribute(DATA_AI_SECTION) ?? void 0;
+}
+function findLabelText(field) {
+  const id = field.getAttribute("id");
+  if (id !== null) {
+    const label = field.ownerDocument?.querySelector(`label[for="${cssEscape(id)}"]`);
+    if (label) {
+      return textPreview(label);
+    }
+  }
+  return textPreview(field.closest("label"));
+}
+function textPreview(node) {
+  const value = node?.textContent?.replace(/\s+/g, " ").trim();
+  return value ? value.slice(0, 160) : void 0;
+}
+function isVisible(element) {
+  const style = element.ownerDocument?.defaultView?.getComputedStyle(element);
+  if (style && (style.display === "none" || style.visibility === "hidden")) {
+    return false;
+  }
+  if (element.hidden || element.getAttribute("aria-hidden") === "true") {
+    return false;
+  }
+  if (typeof element.getClientRects !== "function") {
+    return true;
+  }
+  return element.getClientRects().length > 0 || element === element.ownerDocument?.body;
+}
+function unique(values) {
+  return Array.from(new Set(values));
+}
+function isDefined(value) {
+  return value !== void 0 && value !== null;
+}
+function cssEscape(value) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/["\\]/g, "\\$&");
+}
+
+// src/devtools.ts
+var DEVTOOLS_ROOT_ID = "domglyph-devtools-root";
+var DEVTOOLS_STYLE_ID = "domglyph-devtools-style";
+var INSPECT_SELECTOR = AI_ATTRIBUTE_NAMES.map((name) => `[${name}]`).join(", ");
+function installDOMglyphDevtools(targetWindow = window) {
+  if (typeof targetWindow === "undefined" || targetWindow.document === void 0) {
+    return null;
+  }
+  if (targetWindow.CORTEX_UI_DEVTOOLS !== void 0) {
+    return targetWindow.CORTEX_UI_DEVTOOLS;
+  }
+  const runtime = targetWindow.CORTEX_UI ?? installDOMglyphRuntime(targetWindow);
+  if (runtime === null) {
+    return null;
+  }
+  const devtools = new DOMglyphDevtoolsOverlay(targetWindow, runtime);
+  targetWindow.CORTEX_UI_DEVTOOLS = devtools;
+  return devtools;
+}
+var DOMglyphDevtoolsOverlay = class {
+  constructor(win, runtime) {
+    this.win = win;
+    this.runtime = runtime;
+    this.doc = win.document;
+    ensureStyle(this.doc);
+    this.root = this.doc.createElement("div");
+    this.root.id = DEVTOOLS_ROOT_ID;
+    this.root.style.display = "none";
+    this.root.style.pointerEvents = "none";
+    this.panel = this.doc.createElement("div");
+    this.panel.style.position = "fixed";
+    this.panel.style.top = "16px";
+    this.panel.style.right = "16px";
+    this.panel.style.width = "360px";
+    this.panel.style.maxHeight = "calc(100vh - 32px)";
+    this.panel.style.overflow = "auto";
+    this.panel.style.background = "rgba(10, 19, 16, 0.94)";
+    this.panel.style.color = "#effaf4";
+    this.panel.style.border = "1px solid rgba(255,255,255,0.08)";
+    this.panel.style.borderRadius = "18px";
+    this.panel.style.boxShadow = "0 24px 80px rgba(0,0,0,0.28)";
+    this.panel.style.padding = "16px";
+    this.panel.style.fontFamily = "ui-sans-serif, system-ui, sans-serif";
+    this.panel.style.pointerEvents = "auto";
+    this.panel.style.zIndex = "2147483647";
+    const title = this.doc.createElement("div");
+    title.textContent = "DOMglyph Devtools";
+    title.style.fontSize = "16px";
+    title.style.fontWeight = "700";
+    title.style.marginBottom = "12px";
+    const subtitle = this.doc.createElement("div");
+    subtitle.textContent = "Hover or click any AI-annotated element to inspect metadata.";
+    subtitle.style.color = "rgba(239,250,244,0.72)";
+    subtitle.style.fontSize = "12px";
+    subtitle.style.marginBottom = "16px";
+    const detailBlock = createBlock(this.doc, "Selection");
+    const screenBlock = createBlock(this.doc, "Screen Context");
+    const eventsBlock = createBlock(this.doc, "Recent Events");
+    this.detailPanel = detailBlock.body;
+    this.screenPanel = screenBlock.body;
+    this.eventsPanel = eventsBlock.body;
+    this.panel.append(title, subtitle, detailBlock.wrapper, screenBlock.wrapper, eventsBlock.wrapper);
+    this.hoverBox = createHighlightBox(this.doc, "rgba(55, 148, 255, 0.95)");
+    this.selectedBox = createHighlightBox(this.doc, "rgba(47, 201, 120, 0.95)");
+    this.root.append(this.hoverBox, this.selectedBox, this.panel);
+    (this.doc.body ?? this.doc.documentElement).append(this.root);
+    this.attachListeners();
+    this.render();
+  }
+  doc;
+  root;
+  panel;
+  detailPanel;
+  eventsPanel;
+  screenPanel;
+  hoverBox;
+  selectedBox;
+  disposeCallbacks = [];
+  hoveredElement = null;
+  selectedElement = null;
+  visible = false;
+  refreshTimer = null;
+  show() {
+    if (this.visible) {
+      return;
+    }
+    this.visible = true;
+    this.root.style.display = "block";
+    this.doc.documentElement.setAttribute("data-domglyph-devtools", "open");
+    this.refreshTimer = this.win.setInterval(() => this.render(), 600);
+    this.render();
+  }
+  hide() {
+    if (!this.visible) {
+      return;
+    }
+    this.visible = false;
+    this.root.style.display = "none";
+    this.doc.documentElement.removeAttribute("data-domglyph-devtools");
+    if (this.refreshTimer !== null) {
+      this.win.clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  toggle() {
+    if (this.visible) {
+      this.hide();
+      return false;
+    }
+    this.show();
+    return true;
+  }
+  destroy() {
+    this.hide();
+    for (const dispose of this.disposeCallbacks) {
+      dispose();
+    }
+    this.root.remove();
+    if (this.win.CORTEX_UI_DEVTOOLS === this) {
+      delete this.win.CORTEX_UI_DEVTOOLS;
+    }
+  }
+  isVisible() {
+    return this.visible;
+  }
+  attachListeners() {
+    const onMouseMove = (event) => {
+      const next = event.target instanceof Element ? event.target.closest(INSPECT_SELECTOR) : null;
+      this.hoveredElement = next;
+      this.updateBox(this.hoverBox, next);
+      if (!this.selectedElement) {
+        this.renderSelection(next);
+      }
+    };
+    const onClick = (event) => {
+      const next = event.target instanceof Element ? event.target.closest(INSPECT_SELECTOR) : null;
+      if (next === null) {
+        return;
+      }
+      this.selectedElement = next;
+      this.updateBox(this.selectedBox, next);
+      this.renderSelection(next);
+    };
+    const onScrollOrResize = () => {
+      this.updateBox(this.hoverBox, this.hoveredElement);
+      this.updateBox(this.selectedBox, this.selectedElement);
+    };
+    this.doc.addEventListener("mousemove", onMouseMove, true);
+    this.doc.addEventListener("click", onClick, true);
+    this.win.addEventListener("scroll", onScrollOrResize, true);
+    this.win.addEventListener("resize", onScrollOrResize);
+    this.disposeCallbacks.push(() => this.doc.removeEventListener("mousemove", onMouseMove, true));
+    this.disposeCallbacks.push(() => this.doc.removeEventListener("click", onClick, true));
+    this.disposeCallbacks.push(() => this.win.removeEventListener("scroll", onScrollOrResize, true));
+    this.disposeCallbacks.push(() => this.win.removeEventListener("resize", onScrollOrResize));
+  }
+  updateBox(box, element) {
+    if (element === null || !this.visible) {
+      box.style.display = "none";
+      return;
+    }
+    const rect = element.getBoundingClientRect();
+    box.style.display = rect.width > 0 && rect.height > 0 ? "block" : "none";
+    box.style.transform = `translate(${rect.left + this.win.scrollX}px, ${rect.top + this.win.scrollY}px)`;
+    box.style.width = `${rect.width}px`;
+    box.style.height = `${rect.height}px`;
+  }
+  render() {
+    if (!this.visible) {
+      return;
+    }
+    this.screenPanel.textContent = formatJSON(this.runtime.getScreenContext());
+    this.eventsPanel.textContent = formatJSON(this.runtime.getRecentEvents().slice(0, 12));
+    this.renderSelection(this.selectedElement ?? this.hoveredElement);
+    this.updateBox(this.hoverBox, this.hoveredElement);
+    this.updateBox(this.selectedBox, this.selectedElement);
+  }
+  renderSelection(element) {
+    if (element === null) {
+      this.detailPanel.textContent = "No AI-annotated element selected.";
+      return;
+    }
+    const attrs = extractAIAttributes2(element);
+    const payload = {
+      id: attrs[DATA_AI_ID2],
+      role: attrs[DATA_AI_ROLE2],
+      action: attrs[DATA_AI_ACTION2],
+      state: attrs[DATA_AI_STATE2],
+      tagName: element.tagName.toLowerCase(),
+      text: element.textContent?.trim().slice(0, 160) || void 0,
+      attributes: attrs
+    };
+    this.detailPanel.textContent = formatJSON(payload);
+  }
+};
+function ensureStyle(doc) {
+  if (doc.getElementById(DEVTOOLS_STYLE_ID) !== null) {
+    return;
+  }
+  const style = doc.createElement("style");
+  style.id = DEVTOOLS_STYLE_ID;
+  style.textContent = `
+    html[data-domglyph-devtools="open"] ${INSPECT_SELECTOR} {
+      outline: 1px dashed rgba(47, 201, 120, 0.45);
+      outline-offset: 2px;
+    }
+  `;
+  (doc.head ?? doc.documentElement).append(style);
+}
+function createBlock(doc, label) {
+  const wrapper = doc.createElement("div");
+  wrapper.style.marginBottom = "14px";
+  const heading = doc.createElement("div");
+  heading.textContent = label;
+  heading.style.fontSize = "11px";
+  heading.style.letterSpacing = "0.14em";
+  heading.style.textTransform = "uppercase";
+  heading.style.color = "rgba(239,250,244,0.62)";
+  heading.style.marginBottom = "8px";
+  const body = doc.createElement("pre");
+  body.style.margin = "0";
+  body.style.padding = "12px";
+  body.style.borderRadius = "12px";
+  body.style.background = "rgba(255,255,255,0.05)";
+  body.style.border = "1px solid rgba(255,255,255,0.08)";
+  body.style.font = "12px/1.45 SFMono-Regular, Consolas, monospace";
+  body.style.whiteSpace = "pre-wrap";
+  body.style.wordBreak = "break-word";
+  wrapper.append(heading, body);
+  return { body, wrapper };
+}
+function createHighlightBox(doc, color) {
+  const box = doc.createElement("div");
+  box.style.position = "absolute";
+  box.style.top = "0";
+  box.style.left = "0";
+  box.style.pointerEvents = "none";
+  box.style.border = `2px solid ${color}`;
+  box.style.background = color.replace("0.95", "0.08");
+  box.style.borderRadius = "10px";
+  box.style.boxShadow = `0 0 0 1px ${color}`;
+  box.style.zIndex = "2147483646";
+  box.style.display = "none";
+  return box;
+}
+function formatJSON(value) {
+  return JSON.stringify(value, null, 2) ?? "null";
+}
+
+// src/index.ts
+var runtimeRegistry = {
+  prompt: "browser-inspection-runtime",
+  components: [
+    "getScreenContext",
+    "getAvailableActions",
+    "getFormSchema",
+    "getVisibleEntities",
+    "getRecentEvents"
+  ]
+};
+var defaultRuntimeEvent = AIEvent2.ACTION_TRIGGERED;
+var CORTEX_UI = typeof window === "undefined" ? null : installDOMglyphRuntime(window);
+var CORTEX_UI_DEVTOOLS = typeof window === "undefined" ? null : installDOMglyphDevtools(window);
+export {
+  CORTEX_UI,
+  CORTEX_UI_DEVTOOLS,
+  DOMglyphRuntime,
+  defaultRuntimeEvent,
+  installDOMglyphDevtools,
+  installDOMglyphRuntime,
+  runtimeRegistry
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@domglyph/runtime",
+  "version": "2.0.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"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@domglyph/ai-contract": "2.0.0"
+  },
+  "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"
+  }
+}