@ahtmljs/next 0.1.0

package/dist/handler.js

@@ -0,0 +1,139 @@
+/**
+ * Per-route snapshot handler factory.
+ *
+ * Usage in a Next.js App Router project:
+ *
+ *   // app/ahtml/[...path]/route.ts
+ *   import { createAHTMLRoute } from '@ahtmljs/next/handler';
+ *   import { buildSnapshotForPath } from '../../lib/ahtml';
+ *   export const { GET, HEAD } = createAHTMLRoute(buildSnapshotForPath);
+ *
+ * The handler supports:
+ *   - Content negotiation:
+ *       Accept: application/ahtml+json   → canonical JSON
+ *       Accept: application/ahtml+text   → token-optimal compact text  (default)
+ *   - Conditional GET via If-None-Match → 304
+ *   - Diff endpoint via ?since=<etag>   → SnapshotDiff
+ *   - ETag, Cache-Control, Last-Modified headers
+ *   - Optional policy enforcement (rate limit / auth gate)
+ */
+import { toJson, toCompact, computeEtag, diff, } from '@ahtmljs/schema';
+import { getConfig } from './index.js';
+import { enforcePolicy } from './policy.js';
+/** A simple in-memory store for previous snapshots (per process) so the
+ *  diff endpoint can answer "what changed since <etag>?" without the
+ *  caller re-uploading. Sites with multiple instances should plug in
+ *  their own KV store via setSnapshotCache. */
+const _cache = new Map();
+export function setSnapshotCache(impl) {
+    // override
+    _cache._impl = impl;
+}
+function cacheGet(key) {
+    const impl = _cache._impl;
+    return impl ? impl.get(key) : _cache.get(key);
+}
+function cacheSet(key, s) {
+    const impl = _cache._impl;
+    if (impl)
+        impl.set(key, s);
+    else
+        _cache.set(key, s);
+}
+export function createAHTMLRoute(builder, configOverride) {
+    async function GET(req, ctx) {
+        const config = configOverride ?? getConfig();
+        const params = await ctx.params;
+        const segments = params.path ?? [];
+        const policyDecision = await enforcePolicy(req, config);
+        if (policyDecision.deny)
+            return policyDecision.response;
+        let snap;
+        try {
+            snap = await builder(segments, req);
+        }
+        catch (err) {
+            return error(500, 'snapshot_build_failed', err);
+        }
+        if (!snap) {
+            return error(404, 'no_snapshot', `no snapshot for /${segments.join('/')}`);
+        }
+        snap = ensureDefaults(snap, config);
+        const etag = snap.etag ?? computeEtag(snap);
+        snap.etag = etag;
+        const cacheKey = snap.url;
+        const url = new URL(req.url);
+        // Diff endpoint: GET /ahtml/...?since=W/"abc"
+        const sinceEtag = url.searchParams.get('since');
+        if (sinceEtag) {
+            const prev = cacheGet(cacheKey);
+            if (prev && (prev.etag === sinceEtag || computeEtag(prev) === sinceEtag)) {
+                const d = diff(prev, snap);
+                cacheSet(cacheKey, snap);
+                return new Response(JSON.stringify(d), {
+                    status: 200,
+                    headers: {
+                        'content-type': 'application/ahtml-diff+json',
+                        etag,
+                        'cache-control': cacheControl(snap, config),
+                        'x-ahtml-version': '0.1',
+                    },
+                });
+            }
+            // Fall through to full snapshot if we don't have the prior.
+        }
+        // Conditional GET
+        const ifNoneMatch = req.headers.get('if-none-match');
+        if (ifNoneMatch && ifNoneMatch === etag) {
+            return new Response(null, {
+                status: 304,
+                headers: { etag, 'cache-control': cacheControl(snap, config) },
+            });
+        }
+        cacheSet(cacheKey, snap);
+        const fmt = pickFormat(req);
+        const body = fmt === 'json' ? toJson(snap) : toCompact(snap);
+        return new Response(body, {
+            status: 200,
+            headers: {
+                'content-type': fmt === 'json' ? 'application/ahtml+json' : 'application/ahtml+text; charset=utf-8',
+                etag,
+                'cache-control': cacheControl(snap, config),
+                'last-modified': new Date(snap.fetched_at).toUTCString(),
+                'x-ahtml-version': '0.1',
+                vary: 'Accept',
+            },
+        });
+    }
+    async function HEAD(req, ctx) {
+        const res = await GET(req, ctx);
+        return new Response(null, { status: res.status, headers: res.headers });
+    }
+    return { GET, HEAD };
+}
+function ensureDefaults(snap, config) {
+    if (config.policy && !snap.policy)
+        snap.policy = config.policy;
+    if (config.default_ttl && snap.ttl == null)
+        snap.ttl = config.default_ttl;
+    return snap;
+}
+function cacheControl(snap, config) {
+    const ttl = snap.ttl ?? config.default_ttl ?? 60;
+    return `public, max-age=${ttl}, must-revalidate`;
+}
+function pickFormat(req) {
+    const accept = req.headers.get('accept') ?? '';
+    if (/application\/ahtml\+json/.test(accept))
+        return 'json';
+    if (/application\/ahtml\+text/.test(accept))
+        return 'compact';
+    if (/application\/json/.test(accept) && !/text/.test(accept))
+        return 'json';
+    // Default: compact text. Maximally token-efficient for LLM agents.
+    return 'compact';
+}
+function error(status, code, detail) {
+    return new Response(JSON.stringify({ error: code, detail: detail instanceof Error ? detail.message : String(detail) }), { status, headers: { 'content-type': 'application/json' } });
+}
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @ahtmljs/next — Next.js plugin.
+ *
+ * Quickstart:
+ *
+ *   // next.config.js
+ *   import { withAHTML } from '@ahtmljs/next';
+ *   export default withAHTML({
+ *     // your existing next config
+ *   }, {
+ *     site: 'https://shop.example.com',
+ *     policy: {
+ *       agents_welcome: true,
+ *       license: 'CC-BY-4.0',
+ *       rate_limit: '100/min',
+ *       contact: 'agents@example.com',
+ *     },
+ *   });
+ *
+ *   // app/ahtml/[...path]/route.ts
+ *   import { createAHTMLRoute } from '@ahtmljs/next/handler';
+ *   import { buildSnapshot } from '../../lib/ahtml';
+ *   export const { GET, HEAD } = createAHTMLRoute(buildSnapshot);
+ *
+ *   // app/.well-known/ahtml.json/route.ts
+ *   import { createWellKnownRoute } from '@ahtmljs/next/well-known';
+ *   export const { GET } = createWellKnownRoute();
+ */
+import type { Policy } from '@ahtmljs/schema';
+export interface AHTMLConfig {
+    site: string;
+    policy?: Policy;
+    /** Default TTL in seconds applied to snapshots that don't set their own. */
+    default_ttl?: number;
+    /** Routes that should appear in /.well-known/ahtml.json. */
+    routes?: Array<{
+        path: string;
+        page_type: string;
+    }>;
+    /** Emit MCP tools at /ahtml/mcp.json — default true. */
+    emit_mcp?: boolean;
+    /** Emit OpenAPI at /ahtml/openapi.json — default true. */
+    emit_openapi?: boolean;
+}
+export declare function withAHTML<T extends Record<string, unknown>>(nextConfig: T, ahtmlConfig: AHTMLConfig): T & {
+    __ahtml: AHTMLConfig;
+};
+export declare function getConfig(): AHTMLConfig;
+export type { Policy };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,UAAU,EAAE,CAAC,EACb,WAAW,EAAE,WAAW,GACvB,CAAC,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAM9B;AAED,wBAAgB,SAAS,IAAI,WAAW,CAQvC;AAED,YAAY,EAAE,MAAM,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,48 @@
+/**
+ * @ahtmljs/next — Next.js plugin.
+ *
+ * Quickstart:
+ *
+ *   // next.config.js
+ *   import { withAHTML } from '@ahtmljs/next';
+ *   export default withAHTML({
+ *     // your existing next config
+ *   }, {
+ *     site: 'https://shop.example.com',
+ *     policy: {
+ *       agents_welcome: true,
+ *       license: 'CC-BY-4.0',
+ *       rate_limit: '100/min',
+ *       contact: 'agents@example.com',
+ *     },
+ *   });
+ *
+ *   // app/ahtml/[...path]/route.ts
+ *   import { createAHTMLRoute } from '@ahtmljs/next/handler';
+ *   import { buildSnapshot } from '../../lib/ahtml';
+ *   export const { GET, HEAD } = createAHTMLRoute(buildSnapshot);
+ *
+ *   // app/.well-known/ahtml.json/route.ts
+ *   import { createWellKnownRoute } from '@ahtmljs/next/well-known';
+ *   export const { GET } = createWellKnownRoute();
+ */
+let _config;
+export function withAHTML(nextConfig, ahtmlConfig) {
+    _config = ahtmlConfig;
+    if (typeof globalThis !== 'undefined') {
+        globalThis.__ahtml_config = ahtmlConfig;
+    }
+    return { ...nextConfig, __ahtml: ahtmlConfig };
+}
+export function getConfig() {
+    if (_config)
+        return _config;
+    const g = globalThis.__ahtml_config;
+    if (g)
+        return g;
+    return {
+        site: '',
+        policy: { agents_welcome: true },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAiBH,IAAI,OAAgC,CAAC;AAErC,MAAM,UAAU,SAAS,CACvB,UAAa,EACb,WAAwB;IAExB,OAAO,GAAG,WAAW,CAAC;IACtB,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE,CAAC;QACrC,UAA+C,CAAC,cAAc,GAAG,WAAW,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,CAAC,GAAI,UAA+C,CAAC,cAAc,CAAC;IAC1E,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAChB,OAAO;QACL,IAAI,EAAE,EAAE;QACR,MAAM,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE;KACjC,CAAC;AACJ,CAAC"}

package/dist/llms-txt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * llms.txt emitter — compatibility shim with Jeremy Howard's convention
+ * (Sept 2024). ~10% of sites adopted as of May 2026; used by Cursor /
+ * Continue / Cline / Mintlify-style IDE agents.
+ *
+ * AHTML is a strict superset. We auto-emit /llms.txt from the same
+ * configured routes that feed /.well-known/ahtml.json — adopters get
+ * both lanes for free, with zero extra work.
+ *
+ * Format reference: https://llmstxt.org
+ *
+ *   # Site Name
+ *
+ *   > One-line description of the site
+ *
+ *   ## Section
+ *
+ *   - [Page title](url): one-line description
+ */
+import { type AHTMLConfig } from './index.js';
+export interface LlmsTxtConfig {
+    /** The H1 of the file. Defaults to URL host. */
+    title?: string;
+    /** Blockquote one-liner under the title. */
+    description?: string;
+    /** Optional content groupings — defaults to one untitled section. */
+    sections?: Array<{
+        name: string;
+        items?: Array<{
+            title: string;
+            url: string;
+            description?: string;
+        }>;
+    }>;
+    /** Optional pointer to fuller AHTML manifest. */
+    ahtml_manifest_url?: string;
+}
+export declare function buildLlmsTxt(cfg: LlmsTxtConfig): string;
+export declare function createLlmsTxtRoute(cfgFn?: () => LlmsTxtConfig | Promise<LlmsTxtConfig>, configOverride?: AHTMLConfig): {
+    GET: (_req: Request) => Promise<Response>;
+};
+//# sourceMappingURL=llms-txt.d.ts.map

package/dist/llms-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.d.ts","sourceRoot":"","sources":["../src/llms-txt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrE,CAAC,CAAC;IACH,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA+BvD;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,EAAE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,EACpD,cAAc,CAAC,EAAE,WAAW;gBAEH,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;EA6BrD"}

package/dist/llms-txt.js

@@ -0,0 +1,88 @@
+/**
+ * llms.txt emitter — compatibility shim with Jeremy Howard's convention
+ * (Sept 2024). ~10% of sites adopted as of May 2026; used by Cursor /
+ * Continue / Cline / Mintlify-style IDE agents.
+ *
+ * AHTML is a strict superset. We auto-emit /llms.txt from the same
+ * configured routes that feed /.well-known/ahtml.json — adopters get
+ * both lanes for free, with zero extra work.
+ *
+ * Format reference: https://llmstxt.org
+ *
+ *   # Site Name
+ *
+ *   > One-line description of the site
+ *
+ *   ## Section
+ *
+ *   - [Page title](url): one-line description
+ */
+import { getConfig } from './index.js';
+export function buildLlmsTxt(cfg) {
+    const lines = [];
+    lines.push(`# ${cfg.title ?? 'Site'}`);
+    lines.push('');
+    if (cfg.description) {
+        lines.push(`> ${cfg.description}`);
+        lines.push('');
+    }
+    const sections = cfg.sections && cfg.sections.length
+        ? cfg.sections
+        : [{ name: 'Pages', items: [] }];
+    for (const section of sections) {
+        lines.push(`## ${section.name}`);
+        lines.push('');
+        for (const item of section.items ?? []) {
+            const tail = item.description ? `: ${item.description}` : '';
+            lines.push(`- [${item.title}](${item.url})${tail}`);
+        }
+        lines.push('');
+    }
+    if (cfg.ahtml_manifest_url) {
+        lines.push('## Machine-readable');
+        lines.push('');
+        lines.push(`- [AHTML manifest](${cfg.ahtml_manifest_url}): Structured semantic snapshots, typed actions, MCP-compatible tools, OpenAPI`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function createLlmsTxtRoute(cfgFn, configOverride) {
+    async function GET(_req) {
+        const ahtmlCfg = configOverride ?? getConfig();
+        const cfg = cfgFn
+            ? await cfgFn()
+            : {
+                title: hostFromUrl(ahtmlCfg.site),
+                description: ahtmlCfg.policy?.contact ? `Agents welcome — contact: ${ahtmlCfg.policy.contact}` : undefined,
+                sections: [
+                    {
+                        name: 'Pages',
+                        items: (ahtmlCfg.routes ?? []).map((r) => ({
+                            title: r.path,
+                            url: ahtmlCfg.site.replace(/\/$/, '') + r.path,
+                            description: r.page_type,
+                        })),
+                    },
+                ],
+                ahtml_manifest_url: ahtmlCfg.site.replace(/\/$/, '') + '/.well-known/ahtml.json',
+            };
+        const body = buildLlmsTxt(cfg);
+        return new Response(body, {
+            status: 200,
+            headers: {
+                'content-type': 'text/markdown; charset=utf-8',
+                'cache-control': 'public, max-age=300',
+            },
+        });
+    }
+    return { GET };
+}
+function hostFromUrl(u) {
+    try {
+        return new URL(u).host;
+    }
+    catch {
+        return u;
+    }
+}
+//# sourceMappingURL=llms-txt.js.map

package/dist/llms-txt.js.map

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

package/dist/mcp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Emit MCP (Model Context Protocol) tool definitions from AHTML actions.
+ *
+ * Any AHTML snapshot already carries typed action contracts. By emitting
+ * those at /ahtml/mcp.json, the site automatically exposes itself as an
+ * MCP server-compatible tool surface — no separate MCP server required.
+ */
+import type { Snapshot } from '@ahtmljs/schema';
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+}
+export interface McpManifest {
+    schema_version: '0.1';
+    server: {
+        name: string;
+        url: string;
+    };
+    tools: McpToolDefinition[];
+}
+export declare function snapshotsToMcp(server: {
+    name: string;
+    url: string;
+}, snaps: Snapshot[]): McpManifest;
+export declare function createMcpRoute(getAllSnapshots: () => Snapshot[] | Promise<Snapshot[]>): {
+    GET: (req: Request) => Promise<Response>;
+};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAU,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,KAAK,CAAC;IACtB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,WAAW,CAYpG;AA0BD,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;eAC5D,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;EAapD"}

package/dist/mcp.js

@@ -0,0 +1,64 @@
+/**
+ * Emit MCP (Model Context Protocol) tool definitions from AHTML actions.
+ *
+ * Any AHTML snapshot already carries typed action contracts. By emitting
+ * those at /ahtml/mcp.json, the site automatically exposes itself as an
+ * MCP server-compatible tool surface — no separate MCP server required.
+ */
+export function snapshotsToMcp(server, snaps) {
+    const tools = [];
+    const seen = new Set();
+    for (const s of snaps) {
+        for (const a of s.actions) {
+            const name = `${s.page_type}.${a.id}`;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            tools.push(actionToTool(name, a, s));
+        }
+    }
+    return { schema_version: '0.1', server, tools };
+}
+function actionToTool(name, a, s) {
+    const inputSchema = (a.input && '$ref' in a.input ? { type: 'object' } : a.input) ?? {
+        type: 'object',
+        properties: {},
+    };
+    const annotations = {};
+    if (a.auth)
+        annotations.auth = a.auth;
+    if (a.cost)
+        annotations.cost = a.cost;
+    if (a.reversible)
+        annotations.reversible = a.reversible;
+    if (a.side_effects)
+        annotations.side_effects = a.side_effects;
+    if (a.confirmation)
+        annotations.confirmation = a.confirmation;
+    if (a.rate_limit)
+        annotations.rate_limit = a.rate_limit;
+    if (a.execute_url)
+        annotations.execute_url = a.execute_url;
+    if (a.preview_url)
+        annotations.preview_url = a.preview_url;
+    annotations.snapshot_url = s.url;
+    return {
+        name,
+        description: a.label ?? `${a.category ?? 'action'} on ${s.page_type}`,
+        inputSchema: inputSchema,
+        annotations,
+    };
+}
+export function createMcpRoute(getAllSnapshots) {
+    async function GET(req) {
+        const url = new URL(req.url);
+        const snaps = await getAllSnapshots();
+        const m = snapshotsToMcp({ name: 'ahtml', url: `${url.protocol}//${url.host}` }, snaps);
+        return new Response(JSON.stringify(m, null, 2), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        });
+    }
+    return { GET };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

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

package/dist/openapi.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Emit an OpenAPI 3.1 document describing the snapshot endpoints and
+ * any action endpoints declared on snapshots' actions.
+ */
+import type { Snapshot } from '@ahtmljs/schema';
+export declare function snapshotsToOpenApi(opts: {
+    title: string;
+    baseUrl: string;
+}, snaps: Snapshot[]): Record<string, unknown>;
+export declare function createOpenApiRoute(getAllSnapshots: () => Snapshot[] | Promise<Snapshot[]>): {
+    GET: (req: Request) => Promise<Response>;
+};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0DvH;AAED,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;eAChE,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;EAapD"}

package/dist/openapi.js

@@ -0,0 +1,74 @@
+/**
+ * Emit an OpenAPI 3.1 document describing the snapshot endpoints and
+ * any action endpoints declared on snapshots' actions.
+ */
+export function snapshotsToOpenApi(opts, snaps) {
+    const paths = {};
+    for (const s of snaps) {
+        const path = s.url.replace(opts.baseUrl, '') || '/';
+        const ahtmlPath = '/ahtml' + path;
+        paths[ahtmlPath] = {
+            get: {
+                summary: `AHTML snapshot of ${path}`,
+                responses: {
+                    '200': {
+                        description: 'snapshot',
+                        content: {
+                            'application/ahtml+text': { schema: { type: 'string' } },
+                            'application/ahtml+json': { schema: { $ref: 'https://ahtml.dev/schema/v0.1/snapshot.json' } },
+                        },
+                    },
+                    '304': { description: 'not modified' },
+                },
+            },
+        };
+    }
+    for (const s of snaps) {
+        for (const a of s.actions) {
+            if (!a.execute_url)
+                continue;
+            const verb = (a.method ?? 'post').toLowerCase();
+            const path = (paths[a.execute_url] ??= {});
+            path[verb] = {
+                summary: a.label ?? a.id,
+                operationId: a.id,
+                security: a.auth && a.auth !== 'none' ? [{ bearer: [] }] : undefined,
+                requestBody: a.input ? { content: { 'application/json': { schema: a.input } } } : undefined,
+                responses: {
+                    '200': {
+                        description: 'success',
+                        ...(a.output && { content: { 'application/json': { schema: a.output } } }),
+                    },
+                },
+                'x-ahtml-cost': a.cost,
+                'x-ahtml-reversible': a.reversible,
+                'x-ahtml-side-effects': a.side_effects,
+                'x-ahtml-confirmation': a.confirmation,
+            };
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: opts.title, version: '0.1' },
+        servers: [{ url: opts.baseUrl }],
+        paths,
+        components: {
+            securitySchemes: {
+                bearer: { type: 'http', scheme: 'bearer' },
+            },
+        },
+    };
+}
+export function createOpenApiRoute(getAllSnapshots) {
+    async function GET(req) {
+        const url = new URL(req.url);
+        const snaps = await getAllSnapshots();
+        const doc = snapshotsToOpenApi({ title: 'AHTML', baseUrl: `${url.protocol}//${url.host}` }, snaps);
+        return new Response(JSON.stringify(doc, null, 2), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        });
+    }
+    return { GET };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

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

package/dist/policy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Policy enforcement at the route handler edge.
+ *
+ * AHTML is opt-in. Sites that don't want agents do not install this plugin
+ * and continue to ship HTML behind their existing defenses (CAPTCHA,
+ * Cloudflare, etc). Sites that DO want agents install the plugin and use
+ * this layer to set the terms:
+ *
+ *   - Identity: agents present a user-agent and (optionally) a signed
+ *     identity token from the AI provider.
+ *   - Rate limit: per-IP token bucket.
+ *   - Auth: certain action endpoints require OAuth2 bearer tokens.
+ *
+ * This module ONLY enforces the read side (snapshot fetch). Action
+ * execution is enforced by the host application's own action handlers
+ * — AHTML just publishes the *contract* that says auth is required.
+ */
+import type { AHTMLConfig } from './index.js';
+export interface PolicyDecision {
+    deny: boolean;
+    response: Response;
+}
+export declare function enforcePolicy(req: Request, config: AHTMLConfig): Promise<PolicyDecision>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAOD,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAe9F"}