# NAC3 -- Native Agent Contract

**Version:** 2.3.0-alpha.1 (preview; payload-bearing actions land here)
**Status:** v2.2.x stable + v2.3 preview
**License:** Apache-2.0
**Editor:** Yujin (rpaforce.com)

---

## 0. Purpose

NAC3 is a contract between web UIs and the agents that drive them.
Agents include voice runners, LLM intermediaries, RPA bots,
accessibility tools, and end-to-end test runners. The contract
specifies:

1. **How elements are named** -- so an agent can ask "click the
   save button" and resolve it to a single DOM node.
2. **How verbs apply** -- so an agent can call `NAC.click(id)`,
   `NAC.fill(id, value)`, `NAC.tab(plugin, key)`, etc., without
   per-app glue.
3. **How completion is signalled** -- so an agent knows when a
   step finished, with a deterministic event family per role.
4. **How provenance is preserved** -- so a downstream system can
   tell a real user click from a synthesised one.

NAC3 adds a thin layer on top of whatever framework you already
render with. It does not replace ARIA, React, Vue, or your design
system.

---

## 1. Roles

Every agent-relevant DOM element carries `data-nac-role`. The
canonical roles are:

| Role | Meaning | Example |
|------|---------|---------|
| `plugin` | A self-contained UI module (a page, a panel, a widget collection). | `<article data-nac-plugin="invoice">` |
| `section` | A landmark inside a plugin (header, body, footer, sidebar). | `<section data-nac-role="section">` |
| `region` | A nameable area inside a section (a card cluster, a result list). | `<div data-nac-role="region">` |
| `action` | A clickable widget that triggers a verb (button, link-as-button). | `<button data-nac-role="action" data-nac-action="save">` |
| `field` | An input the user types or toggles (text, number, checkbox, radio, date, file). | `<input data-nac-role="field">` |
| `option` | A selectable option inside a field (combobox / select / radio group child). | `<li data-nac-role="option">` |
| `tab` | A switchable panel selector. **Required when `data-nac-id` matches `^tab\.`** | `<button data-nac-role="tab" data-nac-id="tab.lines">` |
| `breadcrumb-item` | A breadcrumb hop. | `<a data-nac-role="breadcrumb-item">` |
| `accordion-toggle` | An expand/collapse control. | `<button data-nac-role="accordion-toggle">` |
| `step` | A wizard step indicator. | `<li data-nac-role="step">` |
| `pagination-item` | A page-jump control in a paginated list. | `<button data-nac-role="pagination-item">` |
| `confirm-button` | A confirm/cancel button inside a confirm dialog. | `<button data-nac-role="confirm-button">` |
| `sort-control` | A column sort header. | `<th data-nac-role="sort-control">` |
| `filter-control` | A column filter trigger. | `<button data-nac-role="filter-control">` |
| `data-table` | A data-table host (v2.1). | `<table data-nac-role="data-table">` |
| `navigation` | A landmark navigation region. **Not a tab.** | `<nav data-nac-role="navigation">` |
| `confirm-dialog` | The modal of a confirmation request. | `<div data-nac-role="confirm-dialog">` |

Roles outside this list are reserved for future use. A NAC-strict
runtime SHOULD reject unknown roles at register-time (v2.2). A
NAC-permissive runtime MAY treat unknown roles as `action` for
back-compat (v1.9 and v2.0 default).

---

## 2. Names

Every agent-resolvable element carries `data-nac-id`. The id is:

- **A dotted path** (e.g. `deals.list.row.42.actions.delete`).
  Dots separate semantic levels; the runtime does not interpret
  them, but humans and LLMs do.
- **Globally unique within a `data-nac-plugin` scope.** Two
  different plugins MAY share an id; the runtime resolves by
  `(plugin, id)` pair.
- **Stable across re-renders.** Frameworks that produce a new id
  per render (random hashes, instance counters) break the contract.
- **Stable across UI redesigns.** A button moves from the toolbar
  to a dropdown; its id MUST stay the same.

Reserved id prefixes (v2.1):

| Prefix | Reserved for |
|--------|--------------|
| `tab.` | Tab buttons. Role MUST be `tab`. |
| `modal.` | Modal-scoped elements. Role is the leaf widget's role. |
| `field.` | Form field shorthand. Role MUST be `field` or `option`. |
| `confirm.` | Confirm dialogs. |

---

## 3. Verbs

A `data-nac-role="action"` element MAY carry `data-nac-action="<verb>"`
naming what it does. The verb is a free-form snake-case identifier
agreed between the host and the agent. Common verbs:

`save`, `cancel`, `submit`, `delete`, `edit`, `view`, `create`,
`approve`, `reject`, `send`, `download`, `upload`, `refresh`,
`expand`, `collapse`, `open`, `close`, `add_row`, `remove_row`.

`NAC.click_by_verb(plugin, verb)` resolves a verb to the unique
action under that plugin and clicks it. Multiple actions sharing
the same verb under one plugin is a manifest error (lint:
`duplicate_verb`).

---

## 4. Manifest

Every plugin MAY register a manifest via:

```js
NAC.register({
  plugin_slug: 'invoice',
  version:     '1.0.0',
  nac_version: '2.1',
  elements: [
    { id: 'invoice.save', role: 'action',
      actions: [{ verb: 'save', label_i18n: { es: 'Guardar', en: 'Save', ... } }],
      label_i18n: { es: 'Guardar factura', en: 'Save invoice', ... } },
    ...
  ],
  tabs: [
    { nac_id: 'tab.lines', label_i18n: { es: 'Lineas', en: 'Lines' } },
    ...
  ],
  fields: [
    { id: 'field.client_name', type: 'text', required: true,
      label_i18n: { es: 'Cliente', en: 'Customer' } },
    ...
  ],
  data_tables: [...]
});
```

The manifest is the agent-facing source of truth. An LLM
intermediary that decides "the user said 'guardar'" looks up the
plugin manifest, finds the verb `save`, and emits
`NAC.click_by_verb('invoice', 'save')`.

### 4.1 Required fields

- `plugin_slug` -- matches `data-nac-plugin` on the host element.
- `nac_version` -- the NAC3 version this manifest claims to comply
  with. Runtime rejects manifests claiming a version higher than
  itself.

### 4.2 Optional fields

- `elements[]` -- the catalogue of named widgets. Each entry MUST
  have `id` and `role`.
- `tabs[]` -- a separate top-level array for tabs. Equivalent to
  `elements[]` entries with `role:'tab'`. Both shapes valid.
- `fields[]`, `actions[]`, `kpis[]`, `data_tables[]` -- typed
  sub-collections; same semantics as `elements[]` filtered by
  role. Demos pick the shape that reads cleanest to humans.

### 4.3 i18n

Every `label_i18n` MUST cover all 10 NAC3 locales:

```
es, en, pt, fr, ja, zh, hi, ar, de, it
```

`i18n_strict: 'permissive'` on `NAC.autoRegister.watch()` allows
partial coverage during brownfield migration; production manifests
should ship 10 locales.

---

## 5. Public API

### 5.1 Imperative

```ts
NAC.click(nac_id: string, opts?: ClickOpts): Promise<{ok: true}>
NAC.click_by_verb(plugin: string|null, verb: string, opts?): Promise<...>
NAC.fill(nac_id: string, value: string|number|boolean): Promise<...>
NAC.select(nac_id: string, value: string): Promise<...>
NAC.tab(plugin: string, tab_key: string): Promise<...>
NAC.tab_by_label(plugin: string|null, label: string): Promise<...>
NAC.go_to_section(nac_id: string): Promise<...>
NAC.drag_drop(source_id, target_id, opts?: {to_index?: number}): Promise<...>
NAC.set_mode(mode: 'modal'|'maximized'|'new_tab'|'new_window'): void
NAC.screenshot(): Promise<string>  // data URL
NAC.bindAction(el, handler, {plugin, action_id}): () => void  // v2.2
```

### 5.1.1 Conformance helper (v2.2)

`NAC.bindAction(el, handler, ctx)` is the spec-conformant way to
wire a click handler. It emits `nac:action:succeeded` (or
`:failed`) automatically after the handler runs (sync, throw, or
Promise). Returns an unbinder. Use this instead of raw
`addEventListener('click', ...)` whenever the host supports it;
brownfield code can still emit the event manually as before.

### 5.1.3 Field editor (v2.3)

`NAC.edit_field(nac_id)` opens a modal that lets a user (or an
agent on their behalf) edit any text field with Word-style tools:

```ts
NAC.edit_field(nac_id: string): Promise<{ok:true}>
```

The modal registers under `plugin_slug='nac_editor'` with these
NAC-3 callable verbs:

| Verb | Effect |
|------|--------|
| `select_word` | select the word at the caret |
| `select_sentence` | select the sentence at the caret |
| `select_all` | ctrl-A within the editor |
| `replace` | replace selection with given text |
| `delete_selection` | remove current selection |
| `ai_correct_syntax` | POST current value to the LLM intermediary with system prompt "fix grammar + spelling, return only fixed text"; replace value with response |
| `save` | write back to source field, dispatch input + change events, close |
| `cancel` | discard, close |

Esc closes (cancel). Ctrl/Cmd+Enter saves. Click on overlay
backdrop cancels.

Spec sec 13 will formalise the contract in v2.3; the v2.2 runtime
ships a working reference impl so adopters can wire it today.
Available on any field via:

```js
NAC.edit_field('invoice.client_name');
// or by intermediary:
NAC.click_by_verb('myplugin', 'edit_field', { nac_id: 'invoice.client_name' });
```

### 5.1.4 Action payload + invoke (v2.3)

NAC v2.2 actions are click-and-go: an agent triggers `NAC.click(id)`
or `NAC.click_by_verb(plugin, verb)` and the host runs whatever it
does. This works for verb-and-state actions (`save`, `cancel`,
`submit`, `delete`) but collapses when an action needs **data**
from the agent -- `utter(text)`, `search(query)`,
`send_message(body)`, `upload(file)`, `schedule(date)`,
`translate(text, target_lang)`. The host has no way to receive
the agent's payload via a synthetic click.

v2.3 closes this gap. The contract is additive: click-style
verbs continue to work unchanged.

```ts
NAC.invoke(action_id: string, payload: object, opts?: { timeout?: number })
  : Promise<{ok: true, request_id: string, ack: object|null}>

NAC.utter(action_id: string,
          opts: { text: string, lang?: string, voice?: string, metadata?: object })
  : Promise<{ok: true, request_id: string, ack: object|null}>
```

`NAC.invoke` dispatches a `nac:action:requested` `CustomEvent`
on the host element (bubbles to document) with:

```ts
detail: {
  action_id:  string,    // canonical nac_id of the host element
  verb:       string,    // payload.verb || el's data-nac-action
  payload:    object,    // arbitrary, action-specific
  plugin:     string|null,
  request_id: string,    // correlation token assigned by the runtime
  ts:         number,    // Date.now()
}
```

The host listens for `nac:action:requested`, processes the
payload, and emits `nac:action:succeeded` (or `nac:action:failed`)
with the same `request_id` in the detail. The runtime correlates
by `request_id` and resolves the agent's Promise.

Default timeout is **30 seconds** (vs 5 s for click). Override
with `opts.timeout`. On timeout, the Promise rejects with
`NacError('timeout', ...)`. As with click, a timeout means real
failure: callers MUST treat it as such unless they have side-
effect proof via another channel.

`NAC.utter(id, opts)` is the ergonomic shortcut for the most
common payload-bearing verb. It is equivalent to:

```js
NAC.invoke(id, { verb: 'utter', text: opts.text, lang: opts.lang });
```

#### Manifest declaration

A payload-bearing action declares its payload schema in the
manifest entry for traceability and tooling:

```js
NAC.register({
  plugin_slug: 'atlas_pro_ad',
  version:     '2.1.0',
  nac_version: '2.3',
  elements: [
    { id: 'atlas_pro_ad.mic', role: 'action',
      actions: [
        { verb: 'listen' },
        { verb: 'utter',
          payload_schema: {
            text: { type: 'string', required: true, max: 4000 },
            lang: { type: 'string',
                    enum: ['en','es','pt','fr','it','de','ja','zh','hi','ar'] }
          },
          label_i18n: { es:'Decir', en:'Utter', /* ... 10 locales */ } }
      ],
      label_i18n: { /* ... */ } }
  ]
});
```

`payload_schema` is informational in v2.3 stable. Agents MAY
validate before sending; runtimes MAY enforce it when
`STRICT_VALIDATION` is `true`. Schemas are intentionally simple
(JSON-Schema-shaped subset) so a runtime can validate without
shipping a full JSON-Schema validator. v2.4 will formalise the
schema grammar and turn enforcement into a default.

#### Disabled-state semantics (v2.3 hotfix from alpha.2)

`NAC.invoke` does NOT reject when the target element has
`disabled` or `aria-disabled='true'` set. The `disabled` HTML
attribute is a UX click guard; `invoke` is a logical
payload-bearing request, not a synthetic click. Hosts that need
to refuse an invoke based on UI state MUST do it in their
`nac:action:requested` listener and emit `nac:action:failed`
with a meaningful error code.

`NAC.click`, by contrast, STILL rejects on disabled elements
(click semantics preserved). Test coverage:
`packages/nac/test/v23-invoke.mjs` T7/T8/T9.

#### Conformance: hosts that support invoke MUST

1. Declare `actions[].payload_schema` in the manifest entry.
2. Listen for `nac:action:requested` (or use a generic listener
   that filters by `detail.action_id` + `detail.verb`).
3. Emit `nac:action:succeeded` -- with `detail.request_id`
   echoed back -- after processing, or `nac:action:failed`
   (with `detail.error` code) on failure.
4. NEVER emit a `:succeeded` event with a `request_id` they did
   not receive (prevents cross-talk between concurrent invocations).

Hosts that do NOT support invoke continue to operate normally
under `NAC.click()` and `NAC.click_by_verb()`. Agents that call
`NAC.invoke()` against a host without an `actions[].payload_schema`
entry will still receive a `request_id` but the runtime cannot
guarantee delivery; the timeout fires after 30 s.

#### Why this matters

The full agentic surface stops being "list of buttons" and
becomes "list of buttons + structured inputs". A voice ad becomes
NAC.invoke-able. A search bar becomes NAC.invoke-able. A
file upload becomes NAC.invoke-able. Same protocol, same
provenance, same ack semantics.

The first reference adopter is **Atlas Pro** -- its
`atlas_pro_ad.mic` element declares both `listen` (click-only,
existing) and `utter` (payload-bearing) verbs. The same
`/parse` + `/tts` conversational loop drives in either case;
agents that have STT call `listen`, agents that have their own
language model call `utter`.

#### Forward modalities (anticipated, no spec change required)

`invoke` is intentionally modality-agnostic so future input
families plug in without breaking the contract:

| Modality | Verb (sketch)         | Payload (sketch)                                |
|----------|-----------------------|--------------------------------------------------|
| Text     | `utter`               | `{text, lang?}`                                  |
| Search   | `search`              | `{query, scope?, limit?}`                        |
| File     | `upload`              | `{filename, mime, data_url \| stream_id}`        |
| Image    | `analyze_image`       | `{image_url \| data_url, prompt?}`               |
| Video    | `analyze_stream`      | `{stream_url, frame_window_ms?, return?}`        |
| Schedule | `schedule`            | `{datetime, duration_min, attendees?}`           |
| Code     | `apply_diff`          | `{file_path, unified_diff}`                      |
| Voice    | `transcribe`          | `{audio_url \| data_url, lang?}`                 |

Each modality follows the same `nac:action:requested` ->
`nac:action:succeeded` / `:failed` event protocol, the same
`request_id` correlation, the same timeout semantics. The
runtime stays small; the verb vocabulary grows by convention
between hosts and agents. Ergonomic shortcuts (`NAC.utter`,
`NAC.search`, `NAC.watch`, etc.) can be added later without
re-spec because each is a thin wrapper over `invoke`.

### 5.1.5 Shadow DOM resolution -- open roots (v2.3)

The runtime resolves `data-nac-id` references through open
shadow roots recursively. A page can mount Web Components
using `attachShadow({mode:'open'})`, place
`data-nac-*` attributes on elements inside the shadow tree,
and any NAC3 caller (`NAC.click`, `NAC.fill`, `NAC.invoke`,
etc.) resolves the target transparently.

#### Resolution algorithm

For a selector `S` (typically `[data-nac-id="..."]`) against a
root `R` (typically `document`):

1. `R.querySelector(S)` -> if non-null, return immediately.
2. For every descendant `el` of `R`:
   - If `el.shadowRoot` is non-null (i.e. open shadow root):
     recurse with `R := el.shadowRoot`, depth +1.
   - Else if `el.nac3` is an object exposing a `query` method,
     delegate (see sec 5.1.6).
3. The recursion is **depth-capped at 10 levels**. Targets
   deeper than 10 are unreachable; the caller receives
   `code='not_found'`. The cap exists to prevent pathological
   walks; in practice no production codebase nests more than
   3-4 shadow levels.
4. The walk is breadth-of-DOM-order: siblings before nested
   shadows. First match wins.

#### Event propagation

Events emitted by hosts inside shadow roots MUST set
`composed: true` for document-level listeners to receive them.
The NAC3 runtime emits all its own events with `composed:true`
already; host code that emits manual `nac:*` events is
responsible for the same. Without `composed:true` the event
stops at the shadow boundary and the runtime's correlation
machinery never sees it.

#### Author responsibility

The component author needs to:

1. Place `data-nac-id`, `data-nac-role`, `data-nac-action` on
   operable elements inside the shadow root.
2. Set `composed:true` on any custom event the host emits to
   signal a NAC3 contract (`nac:action:succeeded`,
   `nac:field:changed`, etc.).
3. Avoid `<slot>` for elements that need to be
   shadow-isolated -- slotted nodes live in light DOM and are
   resolved there instead.

No manifest hint or runtime opt-in is required for open shadow
roots; the resolution is automatic.

#### Reference implementation

The reference runtime exposes two internal helpers,
`_deepQuery(selector, root)` and
`_deepQueryAll(selector, root)`, that perform the walk. Public
helpers `NAC.click`, `NAC.fill`, `NAC.invoke`,
`NAC.describe`, etc. all go through the deep variants.

#### Demos and tests

- `example-v23-shadow-open.php` -- 1-, 2-, and 3-level nested
  open shadow demos.
- `packages/nac/test/v23-shadow.mjs` T1-T3, T10 -- unit
  coverage including depth cap.

### 5.1.6 Shadow DOM resolution -- closed roots, voluntary exposure (v2.3)

Closed shadow roots (`attachShadow({mode:'closed'})`) are
opaque from outside the component author's code -- a browser
security boundary, not a NAC3 decision. NAC3 cannot reach
inside unless the component author voluntarily exposes a
queriable surface via the contract below.

#### The `el.nac3` interface contract

A custom element MAY expose an interface object on its host
via a getter named `nac3`:

```ts
interface NAC3HostInterface {
  query(selector: string): Element | null;        // MANDATORY
  queryAll(selector: string): Element[];          // RECOMMENDED
  describe?(): Array<{                            // OPTIONAL
    id:    string;
    role:  string;
    action?: string;
    label?: string;
  }>;
}
```

Components opt in by implementing the getter. Components that
do NOT opt in remain inaccessible to NAC3 callers (their
internals stay private, as the browser intends).

#### Resolution semantics

During `_deepQuery(selector)`, for every visited element `el`
with `el.shadowRoot === null`:

1. If `typeof el.nac3 === 'object'` and `el.nac3.query` is a
   function, the runtime calls `el.nac3.query(selector)`:
   - Return value is an Element -> resolved.
   - Return value is `null` -> not a match in this shadow.
   - Return value is anything else -> emit
     `nac:shadow_protocol_violation` (once per host) and skip.
   - Throws -> emit `nac:shadow_blocked` (reason
     `'exposure_threw'`, once per host) and skip.
2. Else if `el.hasAttribute('data-nac-shadow') === true` and
   the attribute value is `'closed'` AND there is no `nac3`
   interface present, the runtime emits `nac:shadow_blocked`
   (reason `'not_exposed'`, once per host). Author opt-in to
   the "I am a deliberately closed component" debug signal.
3. Else: the element is treated as a normal light-DOM
   element with no shadow root.

#### Error event detail shapes

`nac:shadow_blocked` detail:

```ts
{
  host:   Element,     // the closed-shadow host
  reason: 'exposure_threw' | 'not_exposed',
  ts:     number       // Date.now()
}
```

`nac:shadow_protocol_violation` detail:

```ts
{
  host:           Element,
  message:        string,            // diagnostic message
  value_snapshot: string,            // truncated value preview
  ts:             number
}
```

Both events bubble (`bubbles: true`) and cross shadow
boundaries (`composed: true`). Dedup is per-host via a
WeakSet kept by the runtime; the same host emits each event
**at most once per page load**.

#### Why voluntary

The browser enforces closed-shadow opacity. Even if NAC3
defined a non-voluntary mechanism, the browser would prevent
it. Voluntary exposure puts the component author in full
control of what their public surface looks like for agents.

The cost is per-component opt-in; the benefit is that
NAC3-compliant agents work against design systems with closed
shadow components (Salesforce Lightning, some GitHub Primer
components, security-sensitive widgets) without per-component
adapter code.

#### Demos and tests

- `example-v23-shadow-closed.php` -- positive
  (`<todo-card-closed-exposed>`) and negative
  (`<todo-card-closed-blind>`) side-by-side with verdict
  panels + live event log.
- `packages/nac/test/v23-shadow.mjs` T4-T9 -- unit coverage
  for every error event family plus dedup semantics.
- `guides/SHADOW_DOM_CLOSED.md` -- authoring guide.

### 5.1.7 Auth-aware capabilities (v2.3)

NAC3 v2.3 lets the manifest declare per-action capability
requirements that gate `NAC.click` and `NAC.invoke` before
dispatch. The agent receives a fast rejection
(`code='capability_required'`) instead of a round-trip that
fails server-side.

#### Manifest declaration

A capability requirement attaches at the element level or at
the verb level. Verb-level wins if both are present.

```js
NAC.register({
  plugin_slug: 'fin',
  version:     '1.0.0',
  nac_version: '2.3',
  elements: [
    // Element-level (covers all verbs on this id).
    { id: 'fin.invoice.delete', role: 'action',
      requires_capability: 'finance.delete_invoice',
      actions: [{ verb: 'delete' }] },

    // Verb-level (more granular).
    { id: 'fin.invoice.edit', role: 'action',
      actions: [
        { verb: 'edit',
          requires_capability: 'finance.edit_invoice' },
        { verb: 'view',
          /* no capability -> always allowed */ }
      ] },

    // Array value: OR semantics.
    // ("at least one of these capabilities matches")
    { id: 'fin.invoice.approve', role: 'action',
      requires_capability: ['finance.approve',
                            'finance.admin'],
      actions: [{ verb: 'approve' }] }
  ]
});
```

For AND semantics ("user needs ALL of these caps"), declare
each via separate gated actions or compose at the host level
in the `nac:action:requested` listener.

#### Public API

```ts
NAC.setCapabilities(caps: string | string[] | null): void
NAC.grantCapability(cap: string): void
NAC.revokeCapability(cap: string): void
NAC.userCapabilities(): string[]
```

`setCapabilities` replaces the entire set (use for login /
session refresh). `grantCapability` / `revokeCapability` are
incremental. `userCapabilities` returns a snapshot array.
`setCapabilities(null)` clears the set.

Hosts call these whenever the user's role changes. The set
lives in the runtime; no manifest reload is required.

#### Gate semantics

Before dispatch, `NAC.click(id)` and `NAC.invoke(id, payload)`
look up the matching manifest entry (element + verb), read
`requires_capability`, and call `_hasCapability`:

- No requirement declared -> allow.
- Requirement declared, current set satisfies it -> allow.
- Requirement declared, current set does NOT satisfy -> reject
  with `NacError('capability_required', ...)` AND emit
  `nac:command:rejected` with `detail.reason='capability_required'`.

The gate runs AFTER `not_found` / `disabled` / `hidden` checks
on `click` so the most specific failure surfaces. On `invoke`,
the gate runs before the request event fires (the host never
sees an unauthorised attempt).

#### Why this matters

Without the gate, an agent calling `NAC.click('finance.delete')`
either succeeds (no auth gate at all -> security hole) or
fails server-side with a 403 several seconds later. With the
gate, the agent learns synchronously that it lacks the
capability and can react appropriately (request a different
flow, ask for elevation, surface the constraint to the user).

This complements -- it does not replace -- server-side
authorisation. Hosts MUST still enforce permissions on the
server. The client gate is a UX optimisation and an
intent-level signal, not a security boundary.

#### Demos and tests

- `packages/nac/test/v23-capabilities.mjs` -- 17 assertions
  covering set/get, grant/revoke, click gate, invoke gate,
  verb-level vs element-level resolution, OR semantics,
  null-clear, invalid-input rejection, regression for
  unguarded actions.

### 5.1.2 Strict validation flag (v2.2; default-flipped in v2.3)

`NAC.STRICT_VALIDATION` (boolean). When `true`, `NAC.register()`
throws an `Error` with `code='strict_validation'` and a
`findings` array on any of:

- `manifest_role_unknown` -- entry's role outside the canonical set.
- `tab_id_manifest_role_drift` -- id matches `^tab\.` but role
  is not `'tab'`.
- `manifest_dom_role_mismatch` -- mounted DOM element's
  `data-nac-role` differs from manifest entry's role.

**Default value:**

- **v2.2.x:** `false` (warning-only). Adopters needed a migration
  window.
- **v2.3.x:** **`true`** (throwing). The migration window closed
  with the v2.2 line. Adopters with drift-laden manifests opt
  out by setting `NAC.STRICT_VALIDATION = false` BEFORE any
  `register()` call.
- **v3.0:** flag removed (strict is the only mode).

See `guides/MIGRATION_v2.2_to_v2.3.md` for the playbook to clean
up drift findings.

All async methods reject with `NacError` whose `code` is one of:

- `not_found` -- the named element/role/verb is not in the DOM.
- `invalid` -- argument shape is wrong.
- `disabled` -- element has `disabled` or `aria-disabled='true'`
  (`NAC.click` only; `NAC.invoke` no longer checks per v2.3
  hotfix, see sec 5.1.4).
- `hidden` -- element is offscreen / `aria-hidden='true'` /
  zero-dimension.
- `capability_required` -- manifest declared
  `requires_capability` and the current
  `NAC.userCapabilities()` set does not satisfy it (v2.3, see
  sec 5.1.7).
- `timeout` -- side effect dispatched but the conformance ack
  event did not arrive within 5 seconds (30 seconds for
  `invoke`). **A timeout means real failure**: the handler may
  have hung, the ack was never wired, a network race occurred.
  Callers MUST treat timeout as failure unless they have proof
  of side effect via another channel.

### 5.2 Introspection

```ts
NAC.describe():    { active: string|null, plugins: PluginSnap[] }
NAC.describe_v2(): { v2_scope_entries: [...], sitemap: ..., data_tables: [...] }
NAC.manifest(plugin_slug: string): Manifest|null
NAC.validate_global(opts?: {probe?: boolean}): Findings[]
```

### 5.3 Data tables (v2.1)

```ts
NAC.registerDataTable(spec: DataTableSpec): void
NAC.dt_add_row(table_id, values): {ok, row_id}
NAC.dt_remove_row(table_id, row_id): {ok}
NAC.dt_edit_cell(table_id, row_id, column, value): {ok} | {ok:false, error}
NAC.dt_set_cell(table_id, row, col, value): {ok} | {ok:false, error}
NAC.dt_select(table_id, target): {ok}
NAC.dt_commit(table_id): {ok, final_state} | {ok:false, errors:[...]}
NAC.dt_discard(table_id): {ok}
NAC.dt_state(table_id): TableState
NAC.dt_read_aggregate(table_id, agg_key, column): number|null
NAC.registerDataTableComputed(table_id, column, fn): void
```

A data table has a `subkind`:

- `collection` -- ordered rows with optional transactional commit.
  Used for invoice lines, cart items, log entries.
- `matrix` -- row x column grid where every cell carries a value.
  Used for permission matrices, schedule grids.
- `matrix-singletree` -- matrix where each row collapses into a
  tree (rare).

---

## 6. Events

Every action emits a deterministic completion event. The runtime's
`NAC.click()` polls for this event and resolves when it fires.

| Role | Success event | Failure event |
|------|---------------|---------------|
| `action` | `nac:action:succeeded` | `nac:action:failed` |
| `field` | `nac:field:changed` | -- |
| `option` | `nac:field:changed` | -- |
| `tab` | `nac:tab:activated` | -- |
| `breadcrumb-item` | `nac:breadcrumb:navigated` | -- |
| `accordion-toggle` | `nac:accordion:expanded` / `:collapsed` | -- |
| `step` | `nac:step:advanced` | -- |
| `pagination-item` | `nac:table:page_changed` | -- |
| `confirm-button` | `nac:confirm:resolved` / `:cancelled` | -- |
| `sort-control` | `nac:table:sort_changed` | -- |
| `filter-control` | `nac:table:filter_changed` | -- |

### 6.1 Event detail shape

Every event detail carries the canonical id field plus `plugin`:

```js
nac:action:succeeded {
  detail: { plugin: 'invoice', action_id: 'invoice.save', ... }
}
nac:tab:activated {
  detail: { plugin: 'invoice_edit_modal', tab_id: 'tab.lines', ... }
}
nac:field:changed {
  detail: { plugin: 'invoice', field_id: 'field.client_name',
            value: 'Acme Corp', ... }
}
```

### 6.2 Emitting from a host handler

A click handler MUST emit the corresponding success event after
its synchronous side effect:

```js
button.addEventListener('click', function (ev) {
  // ... do the work ...
  document.dispatchEvent(new CustomEvent('nac:action:succeeded', {
    detail: { plugin: 'invoice', action_id: 'invoice.save' }
  }));
});
```

If the work is asynchronous, emit after resolution. If the work
fails, emit `nac:action:failed` with `{detail: {plugin, action_id,
error: <message>}}`.

The v2.2 runtime will provide `NAC.bindAction(el, handler, ctx)`
that wraps `addEventListener` and emits automatically.

### 6.3 Why not use the click event itself?

A DOM `click` event fires before the handler runs. NAC3's contract
needs to know when the **side effect completed**, not when the
click started. Hence the separate event family.

---

## 7. Provenance

### 7.1 isTrusted

`event.isTrusted` is `true` for user-initiated clicks (real mouse,
real keypress, screen reader activation) and `false` for
synthesised clicks (`element.click()`, dispatchEvent of a built
MouseEvent, automation).

NAC3 MUST surface this via `event.detail.is_trusted` in the
success event. Hosts that take security-sensitive actions
(payment, deletion) MAY require `is_trusted === true` and reject
synthetic clicks. The reference demo `example-v20-full.php`
includes a button pair (`v20_panel.istrusted_real` and
`v20_panel.istrusted_fake`) that demonstrates the distinction.

### 7.2 HMAC-signed manifests

A manifest MAY carry a `provenance` block:

```js
NAC.set_provenance_secret('your-tenant-secret');
NAC.register({
  plugin_slug: 'invoice',
  ...,
  provenance: {
    signed_at: '2026-05-09T10:00:00Z',
    signed_by: 'tenant-X',
    signature: '<HMAC-SHA256 of manifest body>'
  }
});
```

The runtime computes the expected HMAC over a stable
serialisation of the manifest (excluding the signature itself)
and rejects manifests whose signature does not match. Used by
multi-tenant deployments to prevent a tenant from spoofing
another tenant's manifest.

### 7.3 Threat model

See `SECURITY.md` for the full threat model. Short version:

- NAC3 does not authenticate the **user**. That is your auth
  layer's job.
- NAC3 authenticates the **manifest** (HMAC).
- NAC3 distinguishes real clicks from synthesised clicks
  (isTrusted) so a host can refuse the latter for sensitive verbs.
- NAC3 does not protect against a malicious agent running with
  user-level access. Such an agent can do anything the user can.

---

## 8. Conformance levels

A page is **NAC-1 conformant** if:

- Every clickable widget that an agent should be able to operate
  carries `data-nac-id` and `data-nac-role`.
- Every `data-nac-role="action"` element fires
  `nac:action:succeeded` after its side effect.
- The page registers at least one plugin manifest via
  `NAC.register()`.
- `NAC.click(id)` works for every advertised id.

A page is **NAC-2 conformant** if it also:

- Registers `tabs[]`, `fields[]`, `actions[]` arrays explicitly
  in its manifest (not inferred from DOM).
- Provides `label_i18n` covering all 10 NAC3 locales for every
  user-facing label.
- Implements the v2.0 brownfield primitives: scope tree,
  ephemeral capture, autoRegister.watch.
- Passes `NAC.validate_global({probe: false})` with zero
  `error`-severity findings.

A page is **NAC-3 conformant** if it also:

- Carries HMAC-signed manifests.
- Distinguishes `isTrusted` for security-sensitive verbs.
- Passes `NAC.validate_global({probe: true})` with zero
  findings.

The NPM package's CLI (`npx @nac3/runtime validate <url>`) reports
the highest level a page reaches.

---

## 9. Versioning

NAC3 follows semver:

- **Major** bump: breaking change to public API or wire formats.
  Adopters edit code.
- **Minor** bump: new features, backward-compatible. Old code
  keeps working.
- **Patch** bump: bug fixes, doc-only changes.

Deprecation policy: a feature marked `@deprecated` in version
`X.Y.0` is removed no earlier than `(X+1).0.0`. The release notes
document every removal explicitly.

The NPM package version mirrors the spec version: `@nac3/runtime@2.1.3`
implements NAC3 v2.1 with three patch revisions.

---

## 10. Validators

### 10.1 Runtime: `NAC.validate_global()`

Walks the live DOM + the registered manifests + the i18n catalog
and returns an array of findings:

```ts
{
  severity: 'error' | 'warn' | 'info',
  code:     string,                     // e.g. 'tab_role_drift'
  nac_id:   string | null,
  message:  string,
  detail:   Record<string, any>
}
```

Findings codes are stable across patch releases; new codes only
in minor bumps.

### 10.2 CLI: `npx @nac3/runtime validate <target>`

Wraps `validate_global` plus a static lint of HTML/manifest
coherence. Exit codes:

- `0` -- no findings of severity >= configured threshold.
- `1` -- findings.
- `2` -- the target itself failed to load.

Useful in CI: `npx @nac3/runtime validate ./dist/index.html
--severity=error`.

---

## 11. The system around NAC3

NAC3 is a contract layer. To turn a NAC-conformant page into a
voice-driven app, you also need:

1. **A speech-to-text source** (browser SpeechRecognition,
   Whisper API, etc).
2. **An LLM intermediary** that takes user text + the page's
   `NAC.describe()` snapshot + an i18n hint and emits structured
   actions: `[{kind: 'click', nac_id: 'X'}, {kind: 'fill', nac_id:
   'Y', value: 'Z'}]`. See `guides/LLM_WIRING.md`.
3. **A chat client** that holds the conversation and dispatches
   the actions. The reference is `js/nac-chat-client.js`.
4. **A text-to-speech sink** for spoken replies (browser
   SpeechSynthesis, ElevenLabs, etc).

NAC3 standardises only step 2's input/output shape (the
`NAC.describe()` snapshot + the action shape). Steps 1, 3, 4 are
outside the spec; you compose what you like.

---

## 12. Stability guarantees

What this spec promises:

1. The set of canonical roles in section 1 will not shrink.
   New roles MAY be added in minor versions.
2. The event family in section 6 will not be renamed.
   New events MAY be added in minor versions.
3. The verbs of `NAC.click`, `NAC.fill`, etc. will not change
   shape in minor versions. New optional `opts` fields MAY appear.
4. The `validate_global` finding codes will not be reused for
   different conditions across minor versions.

What this spec does NOT promise:

1. Precise wording of error messages (those are i18n catalog
   strings; localisations may shift).
2. The DOM strategy for finding elements (`querySelector` today;
   may move to a faster index later).
3. The internal manifest cache layout. Treat manifests as
   write-only from the host side, read-only from the agent side.

---

## 13. Open questions (tracked separately)

- Should `data-nac-role="navigation"` ever resolve to a tab?
  Currently no (v2.1). The v22 roadmap argues for stricter
  rejection.
- Should `NAC.click()` accept relative ids (e.g. `'./save'` to
  mean "save under the active plugin")? Not in v2.1; possibly v2.3.
- Should manifests support inheritance / extension across plugins
  (one base manifest extended by a tenant)? Tracked as v3.0
  candidate.

---

## 13.5 Governance

NAC3 is currently stewarded by Yujin. The spec is published
under Apache 2.0; the reference runtime under MIT. Yujin
commits to moving NAC3 to a neutral foundation (W3C community
group, Linux Foundation, or equivalent industry body) if and
when adoption justifies neutral governance. Until then, spec
changes follow the RFC process documented in
`CONTRIBUTING.md`, with public comment period of at least 14
days for any change that affects the public API or wire
formats.

Adopters: the Apache 2.0 + MIT license combination guarantees
that the spec and runtime survive any change in Yujin's
corporate status. You can fork either, run either, and ship
either, today and after we are gone. This document records
the commitment so the path to that survival is explicit, not
implicit.

---

## 14. Reference implementation

The canonical implementation is the reference runtime distributed
as the NPM package `@nac3/runtime`. The runtime is feature-complete
for v2.1 and ships:

- `js/nac.js` -- v1.9 base + the public API in section 5.
- `js/nac-v2-extensions.js` -- the v2.0 brownfield primitives
  (scope tree, capture ephemeral, autoRegister, HMAC, isTrusted).
- `js/nac-chat-client.js` -- a reference chat client that wires
  voice + LLM + dispatcher.

Other implementations are welcome (Python for native automation
runners, Rust for embedded agents, etc). The spec, not the JS
code, is the authority.

---

*This document is the canonical NAC3 v2.1 specification. Edits to
this file constitute spec changes and require an RFC; see
`CONTRIBUTING.md`.*