@surfaice/format 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 surfaiceai
+
+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,55 @@
+# @surfaice/format
+
+Parser, serializer, and validator for the `.surfaice.md` format — the machine-readable UI description used by [Surfaice](https://github.com/surfaiceai/surfaice).
+
+## Install
+
+```bash
+npm install @surfaice/format
+```
+
+## Usage
+
+```typescript
+import { parse, serialize, validate } from '@surfaice/format'
+
+// Parse a .surfaice.md file
+const page = parse(markdownString)  // → SurfaicePage AST
+
+// Validate structure
+const errors = validate(page)       // → ValidationError[]
+
+// Serialize back to markdown
+const md = serialize(page)          // → string (roundtrip stable)
+```
+
+## What Is `.surfaice.md`?
+
+A markdown-based format that describes your UI elements for AI agents and CI tools:
+
+```markdown
+---
+surfaice: v1
+route: /settings
+states: [auth-required]
+---
+
+# /settings
+
+## Profile
+- [name] textbox "Display Name" → current: {user.name} → accepts: string
+- [save] button "Save Changes" (destructive) → PUT /api/profile → toast 'Saved!'
+```
+
+## API
+
+### `parse(markdown: string): SurfaicePage`
+### `serialize(page: SurfaicePage): string`
+### `validate(page: SurfaicePage): ValidationError[]`
+
+## Part of Surfaice
+
+- [`@surfaice/react`](../react) — React annotations
+- [`@surfaice/differ`](../differ) — Structural diff engine
+- [`@surfaice/cli`](../cli) — CLI tools
+- [`@surfaice/next`](../next) — Next.js middleware

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { ElementType, Element, Section, SurfaicePage, Capability, PageState, StateChange, ValidationError, } from './types.js';
+export { parse } from './parser.js';
+export { serialize } from './serializer.js';
+export { validate } from './validator.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { parse } from './parser.js';
+export { serialize } from './serializer.js';
+export { validate } from './validator.js';

package/dist/parser.d.ts

@@ -0,0 +1,5 @@
+import type { SurfaicePage } from './types.js';
+/**
+ * Parse a .surfaice.md string into a SurfaicePage AST.
+ */
+export declare function parse(input: string): SurfaicePage;

package/dist/parser.js

@@ -0,0 +1,200 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import { parse as parseYaml } from 'yaml';
+// Regex to match element lines: - [id] type "Label" (attrs) → ...
+const ELEMENT_LINE_RE = /^-\s+\[(\w[\w-]*)\]\s+(\w[\w-]*)\s+"([^"]+)"(?:\s+\(([^)]+)\))?(.*)?$/;
+/**
+ * Parse a .surfaice.md string into a SurfaicePage AST.
+ */
+export function parse(input) {
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkFrontmatter, ['yaml']);
+    const mdast = processor.parse(input);
+    // Extract frontmatter
+    const frontmatterNode = mdast.children.find(n => n.type === 'yaml');
+    const frontmatter = frontmatterNode ? parseYaml(frontmatterNode.value) : {};
+    const version = String(frontmatter['surfaice'] ?? 'v1');
+    const route = String(frontmatter['route'] ?? '/');
+    const name = frontmatter['name'] ? String(frontmatter['name']) : undefined;
+    const states = Array.isArray(frontmatter['states']) ? frontmatter['states'].map(String) : undefined;
+    const capabilities = parseCapabilities(frontmatter['capabilities']);
+    // Walk the AST and collect sections + page states
+    const sections = [];
+    let pageStates;
+    let currentSection = null;
+    let inStatesBlock = false;
+    for (const node of mdast.children) {
+        if (node.type === 'yaml')
+            continue;
+        if (node.type === 'heading') {
+            const heading = node;
+            const headingText = extractText(heading);
+            if (heading.depth === 1) {
+                // Page heading — skip
+                currentSection = null;
+                inStatesBlock = false;
+                continue;
+            }
+            if (heading.depth === 2) {
+                if (headingText === 'States') {
+                    inStatesBlock = true;
+                    currentSection = null;
+                }
+                else {
+                    inStatesBlock = false;
+                    currentSection = { name: headingText, elements: [] };
+                    sections.push(currentSection);
+                }
+                continue;
+            }
+        }
+        if (node.type === 'list') {
+            const list = node;
+            if (inStatesBlock) {
+                pageStates = parseStatesBlock(list);
+            }
+            else if (currentSection) {
+                const elements = parseElementList(list);
+                currentSection.elements.push(...elements);
+            }
+        }
+    }
+    return {
+        version,
+        route,
+        ...(name !== undefined && { name }),
+        ...(states !== undefined && { states }),
+        ...(capabilities !== undefined && { capabilities }),
+        sections,
+        ...(pageStates !== undefined && { pageStates }),
+    };
+}
+function parseCapabilities(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.map((cap) => {
+        const c = cap;
+        return {
+            id: String(c['id'] ?? ''),
+            description: String(c['description'] ?? ''),
+            elements: Array.isArray(c['elements']) ? c['elements'].map(String) : [],
+        };
+    });
+}
+function extractText(node) {
+    return node.children
+        .filter((c) => c.type === 'text')
+        .map(c => c.value)
+        .join('');
+}
+function extractListItemText(item) {
+    const para = item.children.find((c) => c.type === 'paragraph');
+    if (!para)
+        return '';
+    return para.children
+        .filter((c) => c.type === 'text')
+        .map(c => c.value)
+        .join('');
+}
+function parseElementList(list) {
+    const elements = [];
+    for (const item of list.children) {
+        const listItem = item;
+        const text = extractListItemText(listItem);
+        const el = parseElementLine(text);
+        if (!el)
+            continue;
+        // Check for nested list (reveals)
+        const nestedList = listItem.children.find((c) => c.type === 'list');
+        if (nestedList) {
+            el.reveals = parseElementList(nestedList);
+        }
+        elements.push(el);
+    }
+    return elements;
+}
+function parseElementLine(line) {
+    const trimmed = line.trim().startsWith('- ') ? line.trim() : `- ${line.trim()}`;
+    const match = trimmed.match(ELEMENT_LINE_RE);
+    if (!match)
+        return null;
+    const [, id, type, label, attrs, rest] = match;
+    const element = {
+        id,
+        type: type,
+        label,
+    };
+    if (attrs) {
+        element.attributes = attrs.split(',').map(a => a.trim()).filter(Boolean);
+    }
+    if (rest && rest.trim()) {
+        parseActions(rest.trim(), element);
+    }
+    return element;
+}
+function parseActions(text, element) {
+    // Split on → (unicode arrow) or ASCII →
+    const parts = text.split(/\s*→\s*/).map(p => p.trim()).filter(Boolean);
+    for (const part of parts) {
+        if (part.startsWith('navigates:')) {
+            element.navigates = part.slice('navigates:'.length).trim();
+        }
+        else if (part.startsWith('current:')) {
+            element.current = part.slice('current:'.length).trim();
+        }
+        else if (part.startsWith('accepts:')) {
+            element.accepts = part.slice('accepts:'.length).trim();
+        }
+        else if (part.startsWith('shows:')) {
+            element.shows = part.slice('shows:'.length).trim();
+        }
+        else if (part.startsWith('options:')) {
+            element.options = part.slice('options:'.length).trim().split(',').map(o => o.trim()).filter(Boolean);
+        }
+        else if (part.startsWith('reveals:')) {
+            // reveals children are parsed from nested list, not inline
+        }
+        else if (/^(GET|POST|PUT|PATCH|DELETE)\s/.test(part)) {
+            element.action = part;
+        }
+        else if (part.startsWith('toast') || part.startsWith('confirms:') || part.startsWith('inline-error')) {
+            element.result = part;
+        }
+        else {
+            // Fallback: first unknown part → action, second → result
+            if (!element.action) {
+                element.action = part;
+            }
+            else if (!element.result) {
+                element.result = part;
+            }
+        }
+    }
+}
+function parseStatesBlock(list) {
+    const states = [];
+    for (const item of list.children) {
+        const text = extractListItemText(item).trim();
+        // Format: [state-name]: modifier elementId description
+        const stateMatch = text.match(/^\[([^\]]+)\]:\s*([+\-~])\s+(\w[\w-]*)\s+(.*)$/);
+        if (!stateMatch)
+            continue;
+        const [, stateName, modifier, elementId, description] = stateMatch;
+        const change = {
+            elementId,
+            modifier: modifier,
+            description: description.trim(),
+        };
+        // Check if we already have this state
+        const existing = states.find(s => s.name === stateName);
+        if (existing) {
+            existing.changes.push(change);
+        }
+        else {
+            states.push({ name: stateName, changes: [change] });
+        }
+    }
+    return states.length > 0 ? states : [];
+}

package/dist/serializer.d.ts

@@ -0,0 +1,6 @@
+import type { SurfaicePage } from './types.js';
+/**
+ * Serialize a SurfaicePage AST back to a .surfaice.md string.
+ * Guarantees roundtrip stability: parse(serialize(page)) deepEquals page.
+ */
+export declare function serialize(page: SurfaicePage): string;

package/dist/serializer.js

@@ -0,0 +1,83 @@
+/**
+ * Serialize a SurfaicePage AST back to a .surfaice.md string.
+ * Guarantees roundtrip stability: parse(serialize(page)) deepEquals page.
+ */
+export function serialize(page) {
+    const lines = [];
+    // Frontmatter
+    lines.push('---');
+    lines.push(`surfaice: ${page.version}`);
+    lines.push(`route: ${page.route}`);
+    if (page.name !== undefined) {
+        lines.push(`name: ${page.name}`);
+    }
+    if (page.states?.length) {
+        lines.push(`states: [${page.states.join(', ')}]`);
+    }
+    if (page.capabilities?.length) {
+        lines.push('capabilities:');
+        for (const cap of page.capabilities) {
+            lines.push(`  - id: ${cap.id}`);
+            lines.push(`    description: "${cap.description}"`);
+            lines.push(`    elements: [${cap.elements.join(', ')}]`);
+        }
+    }
+    lines.push('---');
+    lines.push('');
+    // Page heading
+    lines.push(`# ${page.route}`);
+    // Sections
+    for (const section of page.sections) {
+        lines.push('');
+        lines.push(`## ${section.name}`);
+        for (const el of section.elements) {
+            lines.push(serializeElement(el, 0));
+        }
+    }
+    // Page states
+    if (page.pageStates?.length) {
+        lines.push('');
+        lines.push('## States');
+        for (const state of page.pageStates) {
+            for (const change of state.changes) {
+                lines.push(`- [${state.name}]: ${change.modifier} ${change.elementId} ${change.description}`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function serializeElement(el, indent) {
+    const prefix = '  '.repeat(indent) + '- ';
+    let line = `${prefix}[${el.id}] ${el.type} "${el.label}"`;
+    if (el.attributes?.length) {
+        line += ` (${el.attributes.join(', ')})`;
+    }
+    const parts = [];
+    // Order matters for roundtrip stability — must match parser's parseActions order
+    if (el.current !== undefined)
+        parts.push(`current: ${el.current}`);
+    if (el.accepts !== undefined)
+        parts.push(`accepts: ${el.accepts}`);
+    if (el.options?.length)
+        parts.push(`options: ${el.options.join(', ')}`);
+    if (el.shows !== undefined)
+        parts.push(`shows: ${el.shows}`);
+    if (el.action !== undefined)
+        parts.push(el.action);
+    if (el.result !== undefined)
+        parts.push(el.result);
+    if (el.navigates !== undefined)
+        parts.push(`navigates: ${el.navigates}`);
+    if (el.reveals?.length) {
+        parts.push('reveals:');
+        line += parts.length > 0 ? ' → ' + parts.join(' → ') : '';
+        for (const child of el.reveals) {
+            line += '\n' + serializeElement(child, indent + 1);
+        }
+        return line;
+    }
+    if (parts.length > 0) {
+        line += ' → ' + parts.join(' → ');
+    }
+    return line;
+}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+export type ElementType = 'button' | 'textbox' | 'textarea' | 'link' | 'select' | 'checkbox' | 'radio' | 'toggle' | 'slider' | 'image' | 'image-upload' | 'badge' | 'heading' | 'text' | 'list';
+export interface Capability {
+    /** Unique identifier for this capability, e.g. "update-profile" */
+    id: string;
+    /** Human-readable description, e.g. "User updates their display name" */
+    description: string;
+    /** Element IDs involved in this capability */
+    elements: string[];
+}
+export interface StateChange {
+    /** The element ID this change applies to */
+    elementId: string;
+    /** '+' = add/show, '-' = remove/hide, '~' = modify */
+    modifier: '+' | '-' | '~';
+    /** Description of what changes, e.g. "disabled, shows spinner" */
+    description: string;
+}
+export interface PageState {
+    /** State name, e.g. "loading", "error", "success" */
+    name: string;
+    changes: StateChange[];
+}
+export interface Element {
+    /** Unique identifier within this page, e.g. "save" */
+    id: string;
+    /** Element type */
+    type: ElementType;
+    /** Human-readable label, e.g. "Save Changes" */
+    label: string;
+    /** Optional modifiers: "readonly", "required", "destructive" */
+    attributes?: string[];
+    /** HTTP action, e.g. "PUT /api/profile" */
+    action?: string;
+    /** Side-effect after action, e.g. "toast 'Saved!'" */
+    result?: string;
+    /** Route this element navigates to */
+    navigates?: string;
+    /** Elements revealed after interaction with this element */
+    reveals?: Element[];
+    /** Runtime live value (injected at render time), e.g. "Haosu Wu" */
+    value?: string;
+    /** Template binding for static export, e.g. "{user.name}" */
+    current?: string;
+    /** Input type hint for textboxes, e.g. "email", "string" */
+    accepts?: string;
+    /** Options for select elements */
+    options?: string[];
+    /** Value displayed by display elements (e.g. badge count), e.g. "{notifications.count}" */
+    shows?: string;
+}
+export interface Section {
+    /** Section name, e.g. "Profile Section" */
+    name: string;
+    elements: Element[];
+}
+export interface SurfaicePage {
+    /** Format version, always "v1" for now */
+    version: string;
+    /** Route this page corresponds to, e.g. "/settings" */
+    route: string;
+    /** Optional human-readable page name */
+    name?: string;
+    /** Page-level states that gate access, e.g. ["auth-required"] */
+    states?: string[];
+    /** Named capabilities grouping elements into user flows */
+    capabilities?: Capability[];
+    /** Ordered list of UI sections */
+    sections: Section[];
+    /** Optional state machine describing UI state transitions */
+    pageStates?: PageState[];
+}
+export interface ValidationError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Optional path to the offending node, e.g. "sections[0].elements[2].id" */
+    path?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// @surfaice/format — Core type definitions
+// These types form the AST that everything else produces and consumes.
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,6 @@
+import type { SurfaicePage, ValidationError } from './types.js';
+/**
+ * Validate a SurfaicePage AST for structural correctness.
+ * Returns an array of ValidationErrors — empty array means valid.
+ */
+export declare function validate(page: SurfaicePage): ValidationError[];

package/dist/validator.js

@@ -0,0 +1,102 @@
+const VALID_ELEMENT_TYPES = new Set([
+    'button', 'textbox', 'textarea', 'link', 'select', 'checkbox',
+    'radio', 'toggle', 'slider', 'image', 'image-upload',
+    'badge', 'heading', 'text', 'list',
+]);
+/**
+ * Validate a SurfaicePage AST for structural correctness.
+ * Returns an array of ValidationErrors — empty array means valid.
+ */
+export function validate(page) {
+    const errors = [];
+    // Collect all element IDs for duplicate and reference checking
+    const allIds = new Set();
+    const seenIds = new Set();
+    // First pass: collect all element IDs (including in reveals)
+    for (const section of page.sections) {
+        collectIds(section.elements, allIds);
+    }
+    // Second pass: validate each element and check for duplicates
+    for (let si = 0; si < page.sections.length; si++) {
+        const section = page.sections[si];
+        validateElements(section.elements, seenIds, errors, `sections[${si}]`);
+    }
+    // Validate capabilities reference existing element IDs
+    if (page.capabilities) {
+        for (let ci = 0; ci < page.capabilities.length; ci++) {
+            const cap = page.capabilities[ci];
+            for (const elementId of cap.elements) {
+                if (!allIds.has(elementId)) {
+                    errors.push({
+                        code: 'UNKNOWN_ELEMENT_REF',
+                        message: `Capability "${cap.id}" references unknown element id "${elementId}"`,
+                        path: `capabilities[${ci}].elements`,
+                    });
+                }
+            }
+        }
+    }
+    // Validate page state changes reference existing element IDs
+    if (page.pageStates) {
+        for (let psi = 0; psi < page.pageStates.length; psi++) {
+            const state = page.pageStates[psi];
+            for (let chi = 0; chi < state.changes.length; chi++) {
+                const change = state.changes[chi];
+                if (!allIds.has(change.elementId)) {
+                    errors.push({
+                        code: 'UNKNOWN_ELEMENT_REF',
+                        message: `State "${state.name}" references unknown element id "${change.elementId}"`,
+                        path: `pageStates[${psi}].changes[${chi}].elementId`,
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}
+function collectIds(elements, ids) {
+    for (const el of elements) {
+        ids.add(el.id);
+        if (el.reveals) {
+            collectIds(el.reveals, ids);
+        }
+    }
+}
+function validateElements(elements, seenIds, errors, path) {
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        const elPath = `${path}.elements[${i}]`;
+        // Required fields
+        if (!el.id) {
+            errors.push({ code: 'MISSING_REQUIRED', message: 'Element is missing required field "id"', path: `${elPath}.id` });
+        }
+        if (!el.label) {
+            errors.push({ code: 'MISSING_REQUIRED', message: 'Element is missing required field "label"', path: `${elPath}.label` });
+        }
+        // Valid type
+        if (!VALID_ELEMENT_TYPES.has(el.type)) {
+            errors.push({
+                code: 'INVALID_TYPE',
+                message: `Element "${el.id}" has invalid type "${el.type}". Valid types: ${[...VALID_ELEMENT_TYPES].join(', ')}`,
+                path: `${elPath}.type`,
+            });
+        }
+        // Unique ID
+        if (el.id) {
+            if (seenIds.has(el.id)) {
+                errors.push({
+                    code: 'DUPLICATE_ID',
+                    message: `Duplicate element id "${el.id}" found at ${elPath}`,
+                    path: `${elPath}.id`,
+                });
+            }
+            else {
+                seenIds.add(el.id);
+            }
+        }
+        // Recurse into reveals
+        if (el.reveals) {
+            validateElements(el.reveals, seenIds, errors, `${elPath}.reveals`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@surfaice/format",
+  "version": "0.0.1",
+  "description": "Surfaice format package",
+  "main": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surfaiceai/surfaice",
+    "directory": "packages/format"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.0",
+    "yaml": "^2.4.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  }
+}