Skip to content

sdk-reference.md

Latest commit

 

History

History
217 lines (161 loc) · 5.84 KB

sdk-reference.md

File metadata and controls

217 lines (161 loc) · 5.84 KB

SDK Reference

data-ai-* Attributes

All attributes are optional — untagged elements are discovered automatically by the autotagger.

Attribute Values Description
data-ai-id any string Unique identifier for this element. Used as the primary key in snapshots. Required for manual tagging.
data-ai-role input | action | display | nav Semantic role. input = form field, action = button/link that triggers something, display = read-only content, nav = navigation link.
data-ai-label any string Human-readable label. Used by Claude to understand element purpose. Defaults to element text/placeholder if omitted.
data-ai-action any string Description of what happens when this element is interacted with. E.g. "submits login form".
data-ai-context any string Additional context. E.g. "only visible after authentication".
data-ai-required "true" Mark field as required. Claude uses this when generating test scenarios.
data-ai-state any string Current element state. E.g. "disabled", "loading", "error".

Example

<input
  data-ai-id="email"
  data-ai-role="input"
  data-ai-label="Email address"
  data-ai-required="true"
  type="email"
  placeholder="you@example.com"
/>

<button
  data-ai-id="submit"
  data-ai-role="action"
  data-ai-action="submits login form"
  data-ai-label="Sign in"
>
  Sign in
</button>

getSnapshot() API

Browser (via window.__aiSdk)

const snapshot = window.__aiSdk.getSnapshot(options);

Node / bundler

const aiSdk = require('@phantomui/sdk');
const snapshot = aiSdk.getSnapshot({ root: document });

Options

Option Type Default Description
root Element | Document document DOM node to scan from
autoTag boolean true Include auto-discovered elements (inputs, buttons, links without data-ai-id)
includeHidden boolean false Include hidden inputs in the snapshot

UiSnapshot Shape

interface UiSnapshot {
  url:       string | null;     // current page URL or null
  timestamp: string;            // ISO 8601 capture time
  elements:  ElementDescriptor[];
  warnings?: string[];          // duplicate data-ai-id warnings (if any)
  meta:      SnapshotMeta;
}

interface ElementDescriptor {
  id:       string;             // data-ai-id or auto-generated
  role:     'input' | 'action' | 'display' | 'nav' | null;
  action:   string | null;      // data-ai-action
  label:    string | null;      // data-ai-label
  context:  string | null;      // data-ai-context
  required: boolean;            // data-ai-required === "true"
  state:    string | null;      // data-ai-state
  selector: string;             // CSS selector to reach this element
  source:   'manual' | 'auto'; // how it was discovered
}

interface SnapshotMeta {
  manualCount: number;   // elements with data-ai-id
  autoCount:   number;   // auto-discovered elements
  sdkVersion:  string;   // e.g. "0.1.4"
}

Auto-tagging

When autoTag: true (the default), the SDK scans for:

  • <input>, <textarea>, <select> — tagged as role: 'input'
  • <button>, [type=submit], [role=button] — tagged as role: 'action'
  • <a href> — tagged as role: 'nav'

Auto-tagged elements receive a generated id like auto-input-0. They are always skipped if they already have a data-ai-id attribute.

Framework Adapters

The SDK ships built-in adapters for React, Vue, and Angular. All are zero-dependency wrappers that lazy-load the framework at runtime — they can safely be imported without the framework being globally available.

React — useAiSnapshot hook

Requires React 16.8+ (hooks).

import { useAiSnapshot } from '@phantomui/sdk/adapters/react';

function MyComponent() {
  const { snapshot, refresh, isReady } = useAiSnapshot({ autoTag: true });

  if (!isReady) return <p>Loading snapshot…</p>;

  return (
    <div>
      <p>{snapshot.elements.length} elements found</p>
      <button onClick={refresh}>Re-snapshot</button>
    </div>
  );
}

Options:

Option Type Default Description
autoTag boolean true Include auto-tagged elements
lazy boolean false Don't snapshot on mount; wait for refresh()

Returns: { snapshot, refresh, isReady }

Vue 3 — useAiSnapshot composable + AiSdkPlugin

Composable (Composition API)

import { useAiSnapshot } from '@phantomui/sdk/adapters/vue';

export default {
  setup() {
    const { snapshot, refresh, isReady } = useAiSnapshot({ autoTag: true });
    return { snapshot, refresh, isReady };
  },
};

Plugin (registers $aiSdk globally)

// main.js
import { createApp } from 'vue';
import { AiSdkPlugin } from '@phantomui/sdk/adapters/vue';
import App from './App.vue';

const app = createApp(App);
app.use(AiSdkPlugin, { autoTag: true });
app.mount('#app');

// In any component:
// this.$aiSdk.getSnapshot()
// this.$aiSdk.version

Angular — AiSdkService

Add to your module/component providers, then inject as normal.

// app.module.ts
import { AiSdkService } from '@phantomui/sdk/adapters/angular';

@NgModule({
  providers: [AiSdkService],
})
export class AppModule {}

// my.component.ts
import { AiSdkService } from '@phantomui/sdk/adapters/angular';

@Component({ ... })
export class MyComponent implements OnInit {
  snapshot: any;

  constructor(private aiSdk: AiSdkService) {}

  ngOnInit() {
    this.snapshot = this.aiSdk.getSnapshot();
  }
}

Methods:

Method Returns Description
getSnapshot(options?) UiSnapshot Full snapshot of current page
getElementsByRole(role) ElementDescriptor[] Filter elements by role
getManualElements() ElementDescriptor[] Only manually tagged elements