@atscript/typescript 0.1.26 → 0.1.28

package/README.md

@@ -0,0 +1,50 @@
+# @atscript/typescript
+
+TypeScript language extension for [Atscript](https://atscript.moost.org). Compiles `.as` files into `.d.ts` type declarations and `.js` runtime modules with full metadata, validation, and JSON Schema support.
+
+## Installation
+
+```bash
+pnpm add @atscript/typescript @atscript/core
+```
+
+For build-tool integration (Vite, Webpack, Rollup, esbuild, Rspack), also add:
+
+```bash
+pnpm add unplugin-atscript
+```
+
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx atscript-typescript-skill
+
+# Global (available across all your projects)
+npx atscript-typescript-skill --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "atscript-typescript-skill --postinstall"
+  }
+}
+```
+
+## Features
+
+- **Type declarations** — `.d.ts` files from `.as` interfaces and types
+- **Runtime metadata** — `.js` files with full metadata for validators and serializers
+- **JSON Schema** — Build, parse, and merge JSON schemas from annotated types
+- **Validation** — Validate data against types with plugin support
+- **Serialization** — JSON-safe round-trip serialization/deserialization
+- **CLI** — `asc` command for compiling `.as` files
+
+## Documentation
+
+Full documentation: [atscript.moost.org](https://atscript.moost.org)

package/dist/cli.cjs

@@ -1089,7 +1089,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1176,7 +1176,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1202,7 +1202,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1316,7 +1316,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}

package/dist/index.cjs

@@ -1,4 +1,5 @@
 "use strict";
+Object.defineProperty(exports, '__esModule', { value: true });
 //#region rolldown:runtime
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -1086,7 +1087,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1173,7 +1174,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1199,7 +1200,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1313,7 +1314,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}
@@ -1870,8 +1871,5 @@ else return t.optional ? `${t.type} | true` : t.type;
 };
 
 //#endregion
-//#region packages/typescript/src/index.ts
-var src_default = tsPlugin;
-
-//#endregion
-module.exports = src_default;
+exports.default = tsPlugin
+exports.tsPlugin = tsPlugin

package/dist/index.d.ts

@@ -20,4 +20,4 @@ interface TTsPluginOptions {
 }
 declare const tsPlugin: (opts?: TTsPluginOptions) => TAtscriptPlugin;
 
-export { tsPlugin as default };
+export { tsPlugin as default, tsPlugin };

package/dist/index.mjs

@@ -1062,7 +1062,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1149,7 +1149,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1175,7 +1175,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1289,7 +1289,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}
@@ -1846,8 +1846,4 @@ else return t.optional ? `${t.type} | true` : t.type;
 };
 
 //#endregion
-//#region packages/typescript/src/index.ts
-var src_default = tsPlugin;
-
-//#endregion
-export { src_default as default };
+export { tsPlugin as default, tsPlugin };

package/dist/utils.cjs

@@ -707,7 +707,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -901,6 +901,17 @@ function mergeJsonSchemas(types) {
 		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
 		return undefined;
 	}
+	if (mode === "db") {
+		const dbValue = prop.metadata.get("db.default.value");
+		if (dbValue !== undefined) {
+			const parsed$1 = parseRawValue(dbValue, prop);
+			if (parsed$1 !== undefined && prop.validator({ unknownProps: "ignore" }).validate(parsed$1, true)) return { value: parsed$1 };
+			return undefined;
+		}
+		const dbFn = prop.metadata.get("db.default.fn");
+		if (dbFn !== undefined) return { value: dbFn };
+		return undefined;
+	}
 	const metaKey = mode === "default" ? "meta.default" : "meta.example";
 	const rawStr = prop.metadata.get(metaKey);
 	if (rawStr === undefined) return undefined;

package/dist/utils.d.ts

@@ -354,19 +354,21 @@ interface TCreateDataOptions {
      * - `'empty'` — structural defaults only (`''`, `0`, `false`, `[]`, `{}`); optional props skipped
      * - `'default'` — use `@meta.default` annotations; optional props skipped unless annotated
      * - `'example'` — use `@meta.example` annotations; optional props always included; arrays get one sample item
+     * - `'db'` — use `@db.default.value` (parsed) or `@db.default.fn` (returns fn name string); optional props skipped unless annotated
      * - `function` — custom resolver per field; optional props skipped unless resolver returns a value
      *
      * @default 'empty'
      */
-    mode?: 'empty' | 'default' | 'example' | TValueResolver;
+    mode?: 'empty' | 'default' | 'example' | 'db' | TValueResolver;
 }
 /**
  * Creates a data object from an ATScript annotated type definition.
  *
- * Supports four modes:
+ * Supports five modes:
  * - `'empty'` — structural defaults only; optional props omitted
  * - `'default'` — uses `@meta.default` annotations; optional props omitted unless annotated
  * - `'example'` — uses `@meta.example` annotations; optional props always included; arrays get one sample item
+ * - `'db'` — uses `@db.default.value` (parsed) or `@db.default.fn` (fn name string); optional props omitted unless annotated
  * - `function` — custom resolver; optional props omitted unless resolver returns a value
  *
  * When a `@meta.default` / `@meta.example` value is set on a complex type (object, array)

package/dist/utils.mjs

@@ -706,7 +706,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -900,6 +900,17 @@ function mergeJsonSchemas(types) {
 		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
 		return undefined;
 	}
+	if (mode === "db") {
+		const dbValue = prop.metadata.get("db.default.value");
+		if (dbValue !== undefined) {
+			const parsed$1 = parseRawValue(dbValue, prop);
+			if (parsed$1 !== undefined && prop.validator({ unknownProps: "ignore" }).validate(parsed$1, true)) return { value: parsed$1 };
+			return undefined;
+		}
+		const dbFn = prop.metadata.get("db.default.fn");
+		if (dbFn !== undefined) return { value: dbFn };
+		return undefined;
+	}
 	const metaKey = mode === "default" ? "meta.default" : "meta.example";
 	const rawStr = prop.metadata.get(metaKey);
 	if (rawStr === undefined) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -20,7 +20,7 @@
   },
   "bin": {
     "asc": "./cli.cjs",
-    "setup-skills": "./scripts/setup-skills.js"
+    "atscript-typescript-skill": "./scripts/setup-skills.js"
   },
   "files": [
     "dist",
@@ -57,14 +57,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@moostjs/event-cli": "^0.5.32",
-    "moost": "^0.5.32"
+    "@moostjs/event-cli": "^0.6.2",
+    "moost": "^0.6.2"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.26"
+    "@atscript/core": "^0.1.28"
   },
   "build": [
     {},

package/scripts/setup-skills.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /* prettier-ignore */
 import fs from 'fs'
-import path from 'path'
 import os from 'os'
+import path from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -17,17 +17,18 @@ if (!fs.existsSync(SKILL_SRC)) {
 }
 
 const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+  'Claude Code': { dir: '.claude/skills', global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor': { dir: '.cursor/skills', global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf': { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex': { dir: '.codex/skills', global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode': { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
 }
 
 const args = process.argv.slice(2)
 const isGlobal = args.includes('--global') || args.includes('-g')
 const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
+let installed = 0,
+  skipped = 0
 const installedDirs = []
 
 for (const [agentName, cfg] of Object.entries(AGENTS)) {
@@ -36,7 +37,10 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
 
   // In postinstall mode: silently skip agents that aren't set up globally
   if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+    if (!fs.existsSync(agentRootDir)) {
+      skipped++
+      continue
+    }
   }
 
   const dest = path.join(targetBase, SKILL_NAME)
@@ -55,13 +59,17 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
 if (!isGlobal && installedDirs.length > 0) {
   const gitignorePath = path.join(process.cwd(), '.gitignore')
   let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  try {
+    gitignoreContent = fs.readFileSync(gitignorePath, 'utf8')
+  } catch {}
   const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
   if (linesToAdd.length > 0) {
     const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
+    const block =
+      (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '') +
+      (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n') +
+      linesToAdd.join('\n') +
+      '\n'
     fs.appendFileSync(gitignorePath, block)
     console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
   }
@@ -70,7 +78,9 @@ if (!isGlobal && installedDirs.length > 0) {
 if (installed === 0 && isPostinstall) {
   // Silence is fine — no agents present, nothing to do
 } else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+  console.log(
+    'No agent directories detected. Try --global or run without it for project-local install.'
+  )
 } else if (installed === 0) {
   console.log('Nothing installed. Run without --global to install project-locally.')
 } else {

package/skills/atscript-typescript/SKILL.md

@@ -11,15 +11,15 @@ Atscript is a universal type and metadata description language. `@atscript/types
 
 Read the domain file that matches the task. Do not load all files — only what you need.
 
-| Domain | File | Load when… |
-|--------|------|------------|
-| Setup & configuration | [core.md](core.md) | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI |
-| `.as` file syntax | [syntax.md](syntax.md) | Writing `.as` files — interfaces, types, imports/exports, property syntax |
-| Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*` annotations, defining custom annotations or primitives |
-| Code generation | [codegen.md](codegen.md) | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types |
-| Runtime type system | [runtime.md](runtime.md) | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType` |
-| Validation | [validation.md](validation.md) | Validating data, type guards, error handling, custom validator plugins |
-| Utility functions | [utilities.md](utilities.md) | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType` |
+| Domain                   | File                             | Load when…                                                                                  |
+| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| Setup & configuration    | [core.md](core.md)               | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI         |
+| `.as` file syntax        | [syntax.md](syntax.md)           | Writing `.as` files — interfaces, types, imports/exports, property syntax                   |
+| Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*`/`@ui.*`/`@db.*` annotations, defining custom annotations or primitives |
+| Code generation          | [codegen.md](codegen.md)         | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types      |
+| Runtime type system      | [runtime.md](runtime.md)         | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType`  |
+| Validation               | [validation.md](validation.md)   | Validating data, type guards, error handling, custom validator plugins                      |
+| Utility functions        | [utilities.md](utilities.md)     | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType`   |
 
 ## Quick reference
 
@@ -29,12 +29,20 @@ import tsPlugin from '@atscript/typescript'
 
 // Runtime utilities (used in app code)
 import {
-  defineAnnotatedType, isAnnotatedType, annotate,
-  Validator, ValidatorError,
-  buildJsonSchema, fromJsonSchema, mergeJsonSchemas,
-  serializeAnnotatedType, deserializeAnnotatedType,
-  flattenAnnotatedType, createDataFromAnnotatedType,
-  forAnnotatedType, throwFeatureDisabled,
+  defineAnnotatedType,
+  isAnnotatedType,
+  annotate,
+  Validator,
+  ValidatorError,
+  buildJsonSchema,
+  fromJsonSchema,
+  mergeJsonSchemas,
+  serializeAnnotatedType,
+  deserializeAnnotatedType,
+  flattenAnnotatedType,
+  createDataFromAnnotatedType,
+  forAnnotatedType,
+  throwFeatureDisabled,
 } from '@atscript/typescript/utils'
 
 // CLI

package/skills/atscript-typescript/annotations.md

@@ -6,36 +6,53 @@
 
 ### `@meta.*` — Metadata Annotations
 
-| Annotation | Arguments | Description |
-|------------|-----------|-------------|
-| `@meta.label` | `text: string` | Human-readable label for UI, logs, documentation |
-| `@meta.id` | `name?: string` (optional) | Mark field as unique identifier; optional custom name |
-| `@meta.description` | `text: string` | Detailed description of a field or entity |
-| `@meta.documentation` | `text: string` | Multi-line docs (Markdown). Multiple allowed — each appends |
-| `@meta.placeholder` | `text: string` | Placeholder for UI input fields (props/types only) |
-| `@meta.sensitive` | *(none)* | Mark as sensitive (passwords, API keys). Strips from serialization |
-| `@meta.readonly` | *(none)* | Mark as read-only |
-| `@meta.required` | `message?: string` | Required field. Strings: non-whitespace. Booleans: must be `true` |
-| `@meta.default` | `value: string` | Default value (strings as-is, others parsed as JSON) |
-| `@meta.example` | `value: string` | Example value (strings as-is, others parsed as JSON) |
-| `@meta.isKey` | *(none)* | Mark field as key inside array (string/number types only) |
+| Annotation            | Arguments                  | Description                                                        |
+| --------------------- | -------------------------- | ------------------------------------------------------------------ |
+| `@meta.label`         | `text: string`             | Human-readable label for UI, logs, documentation                   |
+| `@meta.id`            | _(none)_                   | Mark field as unique identifier; multiple fields form composite PK |
+| `@meta.description`   | `text: string`             | Detailed description of a field or entity                          |
+| `@meta.documentation` | `text: string`             | Multi-line docs (Markdown). Multiple allowed — each appends        |
+| `@meta.sensitive`     | _(none)_                   | Mark as sensitive (passwords, API keys). Strips from serialization |
+| `@meta.readonly`      | _(none)_                   | Mark as read-only                                                  |
+| `@meta.required`      | `message?: string`         | Required field. Strings: non-whitespace. Booleans: must be `true`  |
+| `@meta.default`       | `value: string`            | Default value (strings as-is, others parsed as JSON)               |
+| `@meta.example`       | `value: string`            | Example value (strings as-is, others parsed as JSON)               |
+| `@expect.array.key`   | _(none)_                   | Mark field as key inside array (string/number types only)          |
 
 ### `@expect.*` — Validation Constraints
 
-| Annotation | Arguments | Applies To | Description |
-|------------|-----------|-----------|-------------|
-| `@expect.minLength` | `length: number`, `message?: string` | string, array | Minimum length |
-| `@expect.maxLength` | `length: number`, `message?: string` | string, array | Maximum length |
-| `@expect.min` | `minValue: number`, `message?: string` | number | Minimum value |
-| `@expect.max` | `maxValue: number`, `message?: string` | number | Maximum value |
-| `@expect.int` | *(none)* | number | Must be integer |
-| `@expect.pattern` | `pattern: string`, `flags?: string`, `message?: string` | string | Regex validation. **Multiple allowed** (all must pass) |
+| Annotation          | Arguments                                               | Applies To    | Description                                            |
+| ------------------- | ------------------------------------------------------- | ------------- | ------------------------------------------------------ |
+| `@expect.minLength` | `length: number`, `message?: string`                    | string, array | Minimum length                                         |
+| `@expect.maxLength` | `length: number`, `message?: string`                    | string, array | Maximum length                                         |
+| `@expect.min`       | `minValue: number`, `message?: string`                  | number        | Minimum value                                          |
+| `@expect.max`       | `maxValue: number`, `message?: string`                  | number        | Maximum value                                          |
+| `@expect.int`       | _(none)_                                                | number        | Must be integer                                        |
+| `@expect.pattern`   | `pattern: string`, `flags?: string`, `message?: string` | string        | Regex validation. **Multiple allowed** (all must pass) |
+
+### `@ui.*` — UI / Presentation Hints
+
+| Annotation        | Arguments                      | Description                                    |
+| ----------------- | ------------------------------ | ---------------------------------------------- |
+| `@ui.placeholder` | `text: string`                 | Input placeholder text                         |
+| `@ui.component`   | `name: string`                 | UI component hint (`"select"`, `"datepicker"`) |
+| `@ui.hidden`      | _(none)_                       | Hide from UI forms/tables                      |
+| `@ui.group`       | `name: string`                 | Group fields into form sections                |
+| `@ui.order`       | `order: number`                | Display order (lower = first)                  |
+| `@ui.width`       | `width: string`                | Layout hint (`"half"`, `"full"`, `"third"`)    |
+| `@ui.icon`        | `name: string`                 | Icon hint                                      |
+| `@ui.hint`        | `text: string`                 | Help text / tooltip                            |
+| `@ui.disabled`    | _(none)_                       | Non-interactive field                          |
+| `@ui.type`        | `type: string`                 | Input type (`"textarea"`, `"password"`, etc.)  |
+| `@ui.attr`        | `key: string`, `value: string` | Arbitrary attribute (**multiple**, append)      |
+| `@ui.class`       | `names: string`                | CSS class names (**multiple**, append)          |
+| `@ui.style`       | `css: string`                  | Inline CSS styles (**multiple**, append)        |
 
 ### `@emit.*` — Build-time Directives
 
-| Annotation | Applies To | Description |
-|------------|-----------|-------------|
-| `@emit.jsonSchema` | interface | Pre-compute and embed JSON Schema at build time |
+| Annotation         | Applies To | Description                                     |
+| ------------------ | ---------- | ----------------------------------------------- |
+| `@emit.jsonSchema` | interface  | Pre-compute and embed JSON Schema at build time |
 
 ## Custom Annotations
 
@@ -49,21 +66,21 @@ export default defineConfig({
   plugins: [tsPlugin()],
   annotations: {
     // Namespaced annotations use nested objects
-    ui: {
-      // @ui.component "DatePicker"
-      component: new AnnotationSpec({
-        argument: { name: 'name', type: 'string' },
-        description: 'UI component to render this field',
+    grid: {
+      // @grid.column 200
+      column: new AnnotationSpec({
+        argument: { name: 'width', type: 'number' },
+        description: 'Table column width in data grid',
       }),
 
-      // @ui.hidden (no arguments — boolean flag)
+      // @grid.hidden (no arguments — boolean flag)
       hidden: new AnnotationSpec({
-        description: 'Hide this field in the UI',
+        description: 'Hide column in data grid',
       }),
 
-      // @ui.order 5
-      order: new AnnotationSpec({
-        argument: { name: 'position', type: 'number' },
+      // @grid.sortable
+      sortable: new AnnotationSpec({
+        description: 'Allow sorting by this column',
       }),
     },
 
@@ -102,10 +119,10 @@ new AnnotationSpec({
   ],
 
   // Allow multiple instances on the same target
-  multiple: true,               // default: false
+  multiple: true, // default: false
 
   // How duplicates merge: 'replace' (last wins) or 'append' (collect into array)
-  mergeStrategy: 'append',      // default: 'replace'
+  mergeStrategy: 'append', // default: 'replace'
 
   // Human-readable description
   description: 'What this annotation does',
@@ -124,13 +141,13 @@ new AnnotationSpec({
 
 Each argument accepts:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Argument name (used in metadata object key) |
-| `type` | `'string' \| 'number' \| 'boolean'` | Expected type |
-| `optional` | `boolean` | Whether the argument can be omitted |
-| `description` | `string` | Human-readable description |
-| `values` | `string[]` | Allowed values (enum-like constraint) |
+| Field         | Type                                | Description                                 |
+| ------------- | ----------------------------------- | ------------------------------------------- |
+| `name`        | `string`                            | Argument name (used in metadata object key) |
+| `type`        | `'string' \| 'number' \| 'boolean'` | Expected type                               |
+| `optional`    | `boolean`                           | Whether the argument can be omitted         |
+| `description` | `string`                            | Human-readable description                  |
+| `values`      | `string[]`                          | Allowed values (enum-like constraint)       |
 
 ### How Annotations Map to Runtime Metadata
 
@@ -140,6 +157,7 @@ Each argument accepts:
 - **`multiple: true`** → metadata value is an array
 
 Example: `@api.endpoint "/users" "GET"` becomes:
+
 ```ts
 metadata.get('api.endpoint') // → { path: "/users", method: "GET" }
 ```
@@ -200,26 +218,26 @@ export default defineConfig({
 
 ### `TPrimitiveConfig` Options
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `TPrimitiveTypeDef` | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
-| `tags` | `string[]` | Custom tags for categorization |
-| `documentation` | `string` | Documentation string |
-| `expect` | object | Built-in validation constraints |
-| `extensions` | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation |
+| Field           | Type                                        | Description                                                                                      |
+| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `type`          | `TPrimitiveTypeDef`                         | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
+| `tags`          | `string[]`                                  | Custom tags for categorization                                                                   |
+| `documentation` | `string`                                    | Documentation string                                                                             |
+| `expect`        | object                                      | Built-in validation constraints                                                                  |
+| `extensions`    | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation                                                            |
 
 ### `expect` Validation on Primitives
 
-| Field | Applies To | Description |
-|-------|-----------|-------------|
-| `min` | number | Minimum value |
-| `max` | number | Maximum value |
-| `int` | number | Must be integer |
-| `minLength` | string, array | Minimum length |
-| `maxLength` | string, array | Maximum length |
-| `pattern` | string | Regex pattern(s) |
-| `required` | string, boolean | Non-empty / must be true |
-| `message` | any | Custom error message for pattern |
+| Field       | Applies To      | Description                      |
+| ----------- | --------------- | -------------------------------- |
+| `min`       | number          | Minimum value                    |
+| `max`       | number          | Maximum value                    |
+| `int`       | number          | Must be integer                  |
+| `minLength` | string, array   | Minimum length                   |
+| `maxLength` | string, array   | Maximum length                   |
+| `pattern`   | string          | Regex pattern(s)                 |
+| `required`  | string, boolean | Non-empty / must be true         |
+| `message`   | any             | Custom error message for pattern |
 
 ### Usage in `.as` Files