@ahtmljs/schema 0.1.0

package/dist/diff.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Snapshot diffing.
+ *
+ * Given two snapshots (old, new), produce a minimal DiffChange list so
+ * agents can incrementally update their world model without re-fetching
+ * the whole page.
+ *
+ * Diff strategy: structural, by entity/action id. We do NOT attempt deep
+ * field-level patches inside an entity — we replace the whole entity if
+ * any field changed. This trades patch size for diff cost, and the size
+ * trade-off is fine because individual entities are already tiny.
+ */
+import type { Snapshot, SnapshotDiff } from './types.js';
+export declare function diff(prev: Snapshot, next: Snapshot): SnapshotDiff;
+export declare function applyDiff(prev: Snapshot, d: SnapshotDiff): Snapshot;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAA8B,MAAM,YAAY,CAAC;AAGrF,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CA6CjE;AAMD,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,GAAG,QAAQ,CAmBnE"}

package/dist/diff.js

@@ -0,0 +1,90 @@
+/**
+ * Snapshot diffing.
+ *
+ * Given two snapshots (old, new), produce a minimal DiffChange list so
+ * agents can incrementally update their world model without re-fetching
+ * the whole page.
+ *
+ * Diff strategy: structural, by entity/action id. We do NOT attempt deep
+ * field-level patches inside an entity — we replace the whole entity if
+ * any field changed. This trades patch size for diff cost, and the size
+ * trade-off is fine because individual entities are already tiny.
+ */
+import { computeEtag } from './snapshot.js';
+export function diff(prev, next) {
+    const changes = [];
+    const prevEntities = new Map(prev.entities.map((e) => [e.id, e]));
+    const nextEntities = new Map(next.entities.map((e) => [e.id, e]));
+    for (const [id, e] of nextEntities) {
+        const old = prevEntities.get(id);
+        if (!old) {
+            changes.push({ op: 'add', entity: e });
+        }
+        else if (!sameJson(old, e)) {
+            changes.push({ op: 'update', id, patch: e });
+        }
+    }
+    for (const id of prevEntities.keys()) {
+        if (!nextEntities.has(id)) {
+            changes.push({ op: 'remove', id });
+        }
+    }
+    const prevActions = new Map(prev.actions.map((a) => [a.id, a]));
+    const nextActions = new Map(next.actions.map((a) => [a.id, a]));
+    for (const [id, a] of nextActions) {
+        const old = prevActions.get(id);
+        if (!old) {
+            changes.push({ op: 'add_action', action: a });
+        }
+        else if (!sameJson(old, a)) {
+            changes.push({ op: 'remove_action', id });
+            changes.push({ op: 'add_action', action: a });
+        }
+    }
+    for (const id of prevActions.keys()) {
+        if (!nextActions.has(id)) {
+            changes.push({ op: 'remove_action', id });
+        }
+    }
+    return {
+        ahtml: '0.1',
+        url: next.url,
+        from_etag: prev.etag ?? computeEtag(prev),
+        to_etag: next.etag ?? computeEtag(next),
+        changes,
+    };
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function applyDiff(prev, d) {
+    const entities = new Map(prev.entities.map((e) => [e.id, e]));
+    const actions = new Map(prev.actions.map((a) => [a.id, a]));
+    for (const c of d.changes) {
+        switch (c.op) {
+            case 'add':
+                entities.set(c.entity.id, c.entity);
+                break;
+            case 'remove':
+                entities.delete(c.id);
+                break;
+            case 'update':
+                entities.set(c.id, c.patch);
+                break;
+            case 'add_action':
+                actions.set(c.action.id, c.action);
+                break;
+            case 'remove_action':
+                actions.delete(c.id);
+                break;
+        }
+    }
+    return {
+        ...prev,
+        fetched_at: new Date().toISOString(),
+        etag: d.to_etag,
+        entities: [...entities.values()],
+        actions: [...actions.values()],
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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"}

package/dist/format-compact.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Compact text serializer — the token-optimal wire format.
+ *
+ * Why this exists: LLMs tokenize key-value lines and short identifiers much
+ * more efficiently than JSON. By stripping JSON's structural overhead
+ * (quotes, braces, colons, commas, escapes, repeated property names) and
+ * collapsing common shapes (Money → "1999 USD", Stock → "in_stock (42)"),
+ * the same snapshot uses 3–5× fewer tokens.
+ *
+ * Combined with the snapshot itself replacing the underlying HTML, the
+ * end-to-end agent-token reduction is typically 80–200×.
+ *
+ * The format is human-readable, line-oriented, and round-trippable
+ * (see fromCompact). Lossless against canonical JSON.
+ *
+ * Grammar (informal):
+ *
+ *   snapshot   = envelope NL block*
+ *   envelope   = ("@" key value NL)+
+ *   block      = (entity | action | named) NL body
+ *   entity     = "[" type ":" id "]"
+ *   action     = "(action) " id
+ *   named      = "@" name        # policy, provenance, meta, links, schemas
+ *   body       = ("  " key ": " value NL)*
+ */
+import type { Snapshot } from './types.js';
+export declare function toCompact(s: Snapshot): string;
+export declare function fromCompact(text: string): Snapshot;
+//# sourceMappingURL=format-compact.d.ts.map

package/dist/format-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-compact.d.ts","sourceRoot":"","sources":["../src/format-compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAeT,MAAM,YAAY,CAAC;AAEpB,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAsD7C;AAgPD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CA0ElD"}