@surfaice/differ 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,35 @@
+# @surfaice/differ
+
+Structural diff engine for Surfaice pages — compare two `SurfaicePage` ASTs and detect UI drift.
+
+## Install
+
+```bash
+npm install @surfaice/differ @surfaice/format
+```
+
+## Usage
+
+```typescript
+import { diff } from '@surfaice/differ'
+import { parse } from '@surfaice/format'
+
+const expected = parse(committedMarkdown)
+const actual = parse(liveMarkdown)
+
+const result = diff(expected, actual)
+
+if (result.status === 'drift') {
+  console.log(result.summary)  // "2 added, 1 removed, 3 changed"
+  result.added.forEach(el => console.log(`+ [${el.id}] ${el.label}`))
+  result.removed.forEach(el => console.log(`- [${el.id}] ${el.label}`))
+  result.changed.forEach(c => console.log(`~ [${c.id}].${c.field}: "${c.expected}" → "${c.actual}"`))
+}
+```
+
+## What Gets Diffed
+
+- **Added** — elements in actual but not in committed
+- **Removed** — elements in committed but not in actual
+- **Changed** — field-level diffs: `label`, `type`, `action`, `result`, `navigates`, `accepts`, `shows`, `current`, `attributes`, `options`
+- **Nested** — elements inside `reveals` are diffed recursively

package/dist/differ.d.ts

@@ -0,0 +1,7 @@
+import type { SurfaicePage } from '@surfaice/format';
+import type { SurfaiceDiff } from './types.js';
+/**
+ * Diff two SurfaicePage ASTs.
+ * Returns a structured diff with added, removed, and changed elements.
+ */
+export declare function diff(expected: SurfaicePage, actual: SurfaicePage): SurfaiceDiff;

package/dist/differ.js

@@ -0,0 +1,93 @@
+const COMPARED_FIELDS = [
+    'type', 'label', 'action', 'result', 'navigates',
+    'accepts', 'shows', 'current',
+];
+/**
+ * Diff two SurfaicePage ASTs.
+ * Returns a structured diff with added, removed, and changed elements.
+ */
+export function diff(expected, actual) {
+    const expectedMap = buildElementMap(expected);
+    const actualMap = buildElementMap(actual);
+    const added = [];
+    const removed = [];
+    const changed = [];
+    // Removed: in expected, not in actual
+    for (const [id, { element, section }] of expectedMap) {
+        if (!actualMap.has(id)) {
+            removed.push({ id, type: element.type, label: element.label, section });
+        }
+    }
+    // Added: in actual, not in expected
+    for (const [id, { element, section }] of actualMap) {
+        if (!expectedMap.has(id)) {
+            added.push({ id, type: element.type, label: element.label, section });
+        }
+    }
+    // Changed: in both, fields differ
+    for (const [id, { element: exp, section }] of expectedMap) {
+        const actEntry = actualMap.get(id);
+        if (!actEntry)
+            continue;
+        const act = actEntry.element;
+        // Compare scalar fields
+        for (const field of COMPARED_FIELDS) {
+            const expVal = String(exp[field] ?? '');
+            const actVal = String(act[field] ?? '');
+            if (expVal !== actVal && (expVal || actVal)) {
+                changed.push({
+                    id, section, field,
+                    expected: expVal || '(none)',
+                    actual: actVal || '(none)',
+                });
+            }
+        }
+        // Compare attributes (as sorted comma-separated string)
+        const expAttrs = [...(exp.attributes ?? [])].sort().join(', ');
+        const actAttrs = [...(act.attributes ?? [])].sort().join(', ');
+        if (expAttrs !== actAttrs) {
+            changed.push({
+                id, section, field: 'attributes',
+                expected: expAttrs || '(none)',
+                actual: actAttrs || '(none)',
+            });
+        }
+        // Compare options
+        const expOpts = [...(exp.options ?? [])].join(', ');
+        const actOpts = [...(act.options ?? [])].join(', ');
+        if (expOpts !== actOpts && (expOpts || actOpts)) {
+            changed.push({
+                id, section, field: 'options',
+                expected: expOpts || '(none)',
+                actual: actOpts || '(none)',
+            });
+        }
+    }
+    const status = added.length === 0 && removed.length === 0 && changed.length === 0
+        ? 'match'
+        : 'drift';
+    const parts = [];
+    if (added.length)
+        parts.push(`${added.length} added`);
+    if (removed.length)
+        parts.push(`${removed.length} removed`);
+    if (changed.length)
+        parts.push(`${changed.length} changed`);
+    const summary = status === 'match' ? 'No drift detected' : parts.join(', ');
+    return { route: expected.route, status, added, removed, changed, summary };
+}
+function buildElementMap(page) {
+    const map = new Map();
+    for (const section of page.sections) {
+        collectElements(section.elements, section.name, map);
+    }
+    return map;
+}
+function collectElements(elements, section, map) {
+    for (const el of elements) {
+        map.set(el.id, { element: el, section });
+        if (el.reveals?.length) {
+            collectElements(el.reveals, section, map);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { diff } from './differ.js';
+export type { SurfaiceDiff, DiffElement, DiffChange } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @surfaice/differ
+export { diff } from './differ.js';

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface DiffElement {
+    id: string;
+    type: string;
+    label: string;
+    section: string;
+}
+export interface DiffChange {
+    id: string;
+    section: string;
+    /** Which field changed: 'label', 'type', 'action', 'attributes', etc. */
+    field: string;
+    expected: string;
+    actual: string;
+}
+export interface SurfaiceDiff {
+    route: string;
+    status: 'match' | 'drift';
+    added: DiffElement[];
+    removed: DiffElement[];
+    changed: DiffChange[];
+    /** Human-readable one-liner summary */
+    summary: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@surfaice/differ",
+  "version": "0.0.1",
+  "description": "Structural diff engine for Surfaice pages",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surfaiceai/surfaice",
+    "directory": "packages/differ"
+  },
+  "dependencies": {
+    "@surfaice/format": "0.0.1"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0",
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  }
+}