@fatagnus/dink-semantic

Framework-agnostic semantic tree engine for Dink UI. Annotates your component tree with machine-readable roles, intents, state, and actions so copilots, devtools, and plugins can understand and interact with your app.

Install

npm install @fatagnus/dink-semantic

Quick Start

import { SemRoot, Sem, useSemTree } from '@fatagnus/dink-semantic';

function App() {
  return (
    <SemRoot app="my-app" version="1.0.0">
      <Sem semId="dashboard" role="region" label="Dashboard" intent="Main dashboard view">
        <MyDashboard />
      </Sem>
    </SemRoot>
  );
}

Core (no React)

import { SemanticTreeManager } from '@fatagnus/dink-semantic/core';

const manager = new SemanticTreeManager({ app: 'my-app', version: '1.0.0' });
manager.register({ semId: 'root', role: 'application', label: 'My App', parentId: null });
const snapshot = manager.snapshot();

Key Exports

Core (@fatagnus/dink-semantic/core)

| Export | Description | |---|---| | SemanticTreeManager | Headless tree engine -- register/update/unregister nodes, snapshot, act | | SemNode | Node type with role, label, intent, state, actions, ARIA state | | SemTreeSnapshot / SemTreeDelta | Full snapshot and incremental delta types | | SemConsumer / SemEnv | Scoping: 'copilot' \| 'devtools' \| 'webmcp' \| 'plugin' \| '*' |

React Components

| Export | Description | |---|---| | SemRoot | Provider -- initializes SemanticTreeManager, sets app name/version | | Sem | Annotates a DOM subtree with semantic metadata and actions | | SemZone | Lightweight grouping node (no DOM output) |

React Hooks

| Export | Description | |---|---| | useSem | Register a semantic node imperatively, returns update/unregister handles | | useSemTree | Access the tree manager and reactive version counter | | useSemActions | List and invoke actions on any node by semId |

Testing (@fatagnus/dink-semantic/testing)

Mock SemanticTreeManager for unit tests.

Vite Plugin (@fatagnus/dink-semantic/vite)

Strip <Sem> annotations from production builds.

Subpath Exports

• . -- React components + hooks + core (default)
• ./core -- Core engine only (no React dependency)
• ./testing -- Test mocks
• ./vite -- Vite plugin for production stripping

Design Spec

docs/superpowers/specs/2026-03-16-dink-frontend-framework-design.md