@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/openapi.d.ts

@@ -0,0 +1,60 @@
+import type { ApiStructuralDiff, OpenApiSnapshot, OpenApiSummary, SourceBinding } from './types.js';
+export interface LoadedOpenApi {
+    content: string;
+    hash: string;
+    document: Record<string, unknown>;
+    summary: OpenApiSummary;
+    snapshot: OpenApiSnapshot;
+    etag?: string;
+    lastModified?: string;
+    notModified?: boolean;
+}
+export interface RemoteOpenApiCache {
+    url: string;
+    content: string;
+    hash: string;
+    etag?: string;
+    lastModified?: string;
+}
+export interface RemoteFetchOptions {
+    fetch?: typeof globalThis.fetch;
+    resolveHostname?: (hostname: string) => Promise<string[]>;
+    validators?: {
+        etag?: string;
+        lastModified?: string;
+    };
+    cached?: RemoteOpenApiCache;
+    maxBytes?: number;
+}
+/** Parse and validate a JSON or YAML OpenAPI/Swagger document. */
+export declare function parseOpenApi(content: string, location?: string): LoadedOpenApi;
+/** Load and validate either a local file or a safely fetched remote specification. */
+export declare function loadOpenApiSource(root: string, source: SourceBinding, validators?: {
+    etag?: string;
+    lastModified?: string;
+}): Promise<LoadedOpenApi>;
+/** Fetch a remote specification with redirect, SSRF, validator, type, and size controls. */
+export declare function fetchRemoteOpenApi(url: string, options?: RemoteFetchOptions): Promise<RemoteOpenApiCache & {
+    notModified?: boolean;
+}>;
+export declare function diffOpenApi(previous: OpenApiSnapshot | undefined, current: OpenApiSnapshot): ApiStructuralDiff;
+export declare function openApiChangedIdentifiers(diff: ApiStructuralDiff): string[];
+/** Where the plain-text copy of a remote specification is kept for agents to read. */
+export declare function remoteOpenApiCopyPath(root: string, url: string, content?: string): string;
+/** Make sure a remote specification has a readable local copy; returns its path, or undefined for local specs. */
+export declare function ensureRemoteOpenApiCopy(root: string, source: SourceBinding): Promise<string | undefined>;
+/**
+ * The part of a contract one citation names: an operation (`POST /users`,
+ * also reached through an error label such as `POST /users 422`), a schema,
+ * or a security scheme, with every component it references inlined below it
+ * so the writer sees request and response bodies without opening the spec.
+ * A citation that names nothing specific gets the contract's index instead.
+ */
+export declare function openApiExcerpt(document: Record<string, unknown>, citation: {
+    path: string;
+    label?: string;
+}, budget: number): {
+    text: string;
+    truncated: boolean;
+} | undefined;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.js

@@ -0,0 +1,439 @@
+import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { dirname, join, resolve } from 'node:path';
+import { parseDocument, stringify as stringifyYaml } from 'yaml';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+import { isSpecUrl } from './project.js';
+const OPENAPI_CACHE_DIRECTORY = join('.doxloop', 'cache', 'openapi');
+const MAX_SPEC_BYTES = 5 * 1024 * 1024;
+const MAX_REDIRECTS = 3;
+const METHODS = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace'];
+/** Parse and validate a JSON or YAML OpenAPI/Swagger document. */
+export function parseOpenApi(content, location = 'OpenAPI specification') {
+    if (Buffer.byteLength(content, 'utf8') > MAX_SPEC_BYTES) {
+        throw new DoxloopError(`${location} exceeds the 5 MB OpenAPI safety limit.`);
+    }
+    let raw;
+    try {
+        if (content.trimStart().startsWith('{'))
+            raw = JSON.parse(content);
+        else {
+            const yaml = parseDocument(content, { prettyErrors: true });
+            if (yaml.errors.length > 0)
+                throw yaml.errors[0];
+            raw = yaml.toJS({ maxAliasCount: 50 });
+        }
+    }
+    catch (error) {
+        throw new DoxloopError(`${location} is not valid JSON or YAML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(raw))
+        throw new DoxloopError(`${location} must contain an object at the document root.`);
+    const version = text(raw.openapi) ?? text(raw.swagger);
+    if (!version || (!/^3\.\d+(?:\.\d+)?(?:[-+].*)?$/.test(version) && version !== '2.0')) {
+        throw new DoxloopError(`${location} must declare OpenAPI 3.x with "openapi" or Swagger 2.0 with "swagger".`);
+    }
+    const info = record(raw.info);
+    const title = text(info.title);
+    const apiVersion = text(info.version);
+    if (!title)
+        throw new DoxloopError(`${location} is missing the required info.title.`);
+    if (!apiVersion)
+        throw new DoxloopError(`${location} is missing the required info.version.`);
+    const paths = record(raw.paths);
+    if (Object.keys(paths).some((path) => !path.startsWith('/'))) {
+        throw new DoxloopError(`${location} contains a path key that does not start with "/".`);
+    }
+    const snapshot = openApiSnapshot(raw, version);
+    const servers = array(raw.servers).flatMap((item) => text(record(item).url) ?? []);
+    if (version === '2.0' && text(raw.host))
+        servers.push(`${array(raw.schemes).flatMap(text)[0] ?? 'https'}://${text(raw.host)}${text(raw.basePath) ?? ''}`);
+    const summary = {
+        title,
+        version: apiVersion,
+        specificationVersion: version,
+        servers,
+        securitySchemes: Object.keys(snapshot.securitySchemes).sort(),
+        schemas: Object.keys(snapshot.schemas).sort(),
+        operationCount: Object.keys(snapshot.operations).length,
+    };
+    return {
+        content,
+        hash: createHash('sha256').update(content).digest('hex'),
+        document: raw,
+        summary,
+        snapshot,
+    };
+}
+/** Load and validate either a local file or a safely fetched remote specification. */
+export async function loadOpenApiSource(root, source, validators) {
+    if (!isSpecUrl(source.path)) {
+        const path = resolve(root, source.path);
+        let content;
+        try {
+            content = await readFile(path, 'utf8');
+        }
+        catch {
+            throw new DoxloopError(`The API specification does not exist or cannot be read: ${path}`);
+        }
+        return parseOpenApi(content, source.path);
+    }
+    const cached = await readRemoteCache(root, source.path);
+    const effectiveValidators = validators ?? (cached ? { ...(cached.etag ? { etag: cached.etag } : {}), ...(cached.lastModified ? { lastModified: cached.lastModified } : {}) } : undefined);
+    const remote = await fetchRemoteOpenApi(source.path, { ...(effectiveValidators ? { validators: effectiveValidators } : {}), ...(cached ? { cached } : {}) });
+    const parsed = parseOpenApi(remote.content, source.path);
+    const result = {
+        ...parsed,
+        ...(remote.etag ? { etag: remote.etag } : {}),
+        ...(remote.lastModified ? { lastModified: remote.lastModified } : {}),
+        ...(remote.notModified ? { notModified: true } : {}),
+    };
+    await writeRemoteCache(root, source.path, result);
+    return result;
+}
+/** Fetch a remote specification with redirect, SSRF, validator, type, and size controls. */
+export async function fetchRemoteOpenApi(url, options = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const resolveHostname = options.resolveHostname ?? defaultResolveHostname;
+    const maxBytes = options.maxBytes ?? MAX_SPEC_BYTES;
+    let current = safeRemoteUrl(url);
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+        await assertPublicRemote(current, resolveHostname);
+        const headers = new Headers({ accept: 'application/json, application/yaml, application/x-yaml, text/yaml, text/plain;q=0.5' });
+        if (redirects === 0 && options.validators?.etag)
+            headers.set('if-none-match', options.validators.etag);
+        if (redirects === 0 && options.validators?.lastModified)
+            headers.set('if-modified-since', options.validators.lastModified);
+        const response = await fetcher(current, { method: 'GET', redirect: 'manual', headers, signal: AbortSignal.timeout(15_000) });
+        if (response.status === 304) {
+            if (!options.cached)
+                throw new DoxloopError(`Remote OpenAPI returned 304 but no cached document is available.`);
+            return { ...options.cached, notModified: true };
+        }
+        if (response.status >= 300 && response.status < 400) {
+            if (redirects === MAX_REDIRECTS)
+                throw new DoxloopError(`Remote OpenAPI redirect limit exceeded for ${url}.`);
+            const location = response.headers.get('location');
+            if (!location)
+                throw new DoxloopError(`Remote OpenAPI redirect from ${current} did not include a location.`);
+            current = safeRemoteUrl(new URL(location, current).toString());
+            continue;
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new DoxloopError(`Remote OpenAPI credentials are required. Configure a credential-free or pre-signed HTTPS URL; credentials are never stored by Doxloop.`);
+        }
+        if (!response.ok)
+            throw new DoxloopError(`Remote OpenAPI request failed with HTTP ${response.status}.`);
+        assertOpenApiContentType(response.headers.get('content-type'), current);
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > maxBytes)
+            throw new DoxloopError(`Remote OpenAPI exceeds the ${formatBytes(maxBytes)} safety limit.`);
+        const content = await boundedResponseText(response, maxBytes);
+        return {
+            url: current,
+            content,
+            hash: createHash('sha256').update(content).digest('hex'),
+            ...(response.headers.get('etag') ? { etag: response.headers.get('etag') } : {}),
+            ...(response.headers.get('last-modified') ? { lastModified: response.headers.get('last-modified') } : {}),
+        };
+    }
+    throw new DoxloopError(`Remote OpenAPI request could not be completed.`);
+}
+export function diffOpenApi(previous, current) {
+    if (!previous) {
+        return {
+            operations: { added: Object.keys(current.operations), removed: [], changed: [] },
+            schemas: { added: Object.keys(current.schemas), removed: [], changed: [] },
+            securitySchemes: { added: Object.keys(current.securitySchemes), removed: [], changed: [] },
+        };
+    }
+    return {
+        operations: diffSnapshotRecords(previous.operations, current.operations, operationFacets),
+        schemas: diffSnapshotRecords(previous.schemas, current.schemas),
+        securitySchemes: diffSnapshotRecords(previous.securitySchemes, current.securitySchemes),
+    };
+}
+export function openApiChangedIdentifiers(diff) {
+    return [
+        ...diff.operations.added,
+        ...diff.operations.removed,
+        ...diff.operations.changed.map((item) => item.id),
+        ...diff.schemas.added.map((item) => `schema:${item}`),
+        ...diff.schemas.removed.map((item) => `schema:${item}`),
+        ...diff.schemas.changed.map((item) => `schema:${item.id}`),
+        ...diff.securitySchemes.added.map((item) => `security:${item}`),
+        ...diff.securitySchemes.removed.map((item) => `security:${item}`),
+        ...diff.securitySchemes.changed.map((item) => `security:${item.id}`),
+    ];
+}
+function openApiSnapshot(document, specificationVersion) {
+    const operations = {};
+    for (const [path, rawPath] of Object.entries(record(document.paths))) {
+        const pathItem = record(rawPath);
+        for (const method of METHODS) {
+            if (!(method in pathItem) || !isRecord(pathItem[method]))
+                continue;
+            const operation = record(pathItem[method]);
+            const id = `${method.toUpperCase()} ${path}`;
+            const parameters = [...array(pathItem.parameters), ...array(operation.parameters)];
+            operations[id] = {
+                operationId: text(operation.operationId) ?? '',
+                parameters: stableHash(parameters),
+                requestBody: stableHash(operation.requestBody),
+                responses: stableHash(operation.responses),
+                security: stableHash(operation.security ?? document.security),
+                examples: stableHash(operationExamples(operation)),
+                full: stableHash(operation),
+            };
+        }
+    }
+    const schemasSource = specificationVersion === '2.0'
+        ? record(document.definitions)
+        : record(record(document.components).schemas);
+    const securitySource = specificationVersion === '2.0'
+        ? record(document.securityDefinitions)
+        : record(record(document.components).securitySchemes);
+    return {
+        schemaVersion: 1,
+        specificationVersion,
+        operations,
+        schemas: hashRecord(schemasSource),
+        securitySchemes: hashRecord(securitySource),
+    };
+}
+function operationFacets(before, after) {
+    return ['operationId', 'parameters', 'requestBody', 'responses', 'security', 'examples']
+        .filter((facet) => before[facet] !== after[facet]);
+}
+function diffSnapshotRecords(before, after, facets) {
+    const beforeKeys = new Set(Object.keys(before));
+    const afterKeys = new Set(Object.keys(after));
+    const added = [...afterKeys].filter((key) => !beforeKeys.has(key)).sort();
+    const removed = [...beforeKeys].filter((key) => !afterKeys.has(key)).sort();
+    const changed = [...beforeKeys].filter((key) => afterKeys.has(key) && stableHash(before[key]) !== stableHash(after[key])).sort().map((id) => ({
+        id,
+        facets: facets && isRecord(before[id]) && isRecord(after[id]) ? facets(before[id], after[id]) : ['definition'],
+    }));
+    return { added, removed, changed };
+}
+function hashRecord(value) {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, stableHash(item)]));
+}
+function operationExamples(operation) {
+    return {
+        examples: operation.examples,
+        requestBody: record(operation.requestBody).content,
+        responses: Object.fromEntries(Object.entries(record(operation.responses)).map(([status, response]) => [status, record(response).content])),
+    };
+}
+function stableHash(value) {
+    return createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (isRecord(value))
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+async function boundedResponseText(response, maximum) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (true) {
+        const next = await reader.read();
+        if (next.done)
+            break;
+        size += next.value.byteLength;
+        if (size > maximum) {
+            await reader.cancel();
+            throw new DoxloopError(`Remote OpenAPI exceeds the ${formatBytes(maximum)} safety limit.`);
+        }
+        chunks.push(next.value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function safeRemoteUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new DoxloopError(`Invalid remote OpenAPI URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw new DoxloopError('Remote OpenAPI URLs must use HTTP or HTTPS.');
+    if (url.username || url.password)
+        throw new DoxloopError('Remote OpenAPI URLs cannot contain embedded credentials.');
+    if (url.hash)
+        url.hash = '';
+    return url.toString();
+}
+async function assertPublicRemote(url, resolver) {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname.endsWith('.local')) {
+        throw new DoxloopError('Remote OpenAPI URLs cannot target localhost or private networks.');
+    }
+    const addresses = isIP(hostname) ? [hostname] : await resolver(hostname);
+    if (addresses.length === 0 || addresses.some(isPrivateAddress)) {
+        throw new DoxloopError('Remote OpenAPI URLs cannot target localhost or private networks.');
+    }
+}
+async function defaultResolveHostname(hostname) {
+    try {
+        return (await lookup(hostname, { all: true })).map((item) => item.address);
+    }
+    catch {
+        throw new DoxloopError(`Remote OpenAPI host could not be resolved: ${hostname}`);
+    }
+}
+function isPrivateAddress(address) {
+    const normalized = address.toLowerCase().replace(/^::ffff:/, '');
+    if (normalized === '::1' || normalized === '::' || normalized.startsWith('fc') || normalized.startsWith('fd') || normalized.startsWith('fe8') || normalized.startsWith('fe9') || normalized.startsWith('fea') || normalized.startsWith('feb'))
+        return true;
+    const parts = normalized.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part)))
+        return false;
+    const first = parts[0] ?? -1;
+    return first === 0 || first === 10 || first === 127 || (first === 169 && parts[1] === 254) || (first === 172 && (parts[1] ?? 0) >= 16 && (parts[1] ?? 0) <= 31) || (first === 192 && parts[1] === 168) || first >= 224;
+}
+function assertOpenApiContentType(raw, url) {
+    const type = raw?.split(';')[0]?.trim().toLowerCase();
+    const supported = new Set(['application/json', 'application/yaml', 'application/x-yaml', 'text/yaml', 'text/x-yaml', 'text/plain', 'application/octet-stream']);
+    if (type && !supported.has(type) && !/\.(json|ya?ml)$/i.test(new URL(url).pathname)) {
+        throw new DoxloopError(`Remote OpenAPI returned unsupported content type "${type}". Expected JSON or YAML.`);
+    }
+}
+async function readRemoteCache(root, url) {
+    const path = remoteCachePath(root, url);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.url === url && typeof value.content === 'string' && typeof value.hash === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeRemoteCache(root, url, loaded) {
+    const path = remoteCachePath(root, url);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ url, content: loaded.content, hash: loaded.hash, etag: loaded.etag, lastModified: loaded.lastModified }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    // Writing agents run without network access and cannot read the URL; they
+    // read this plain copy of the specification instead.
+    await writeFile(remoteOpenApiCopyPath(root, url, loaded.content), loaded.content, { encoding: 'utf8', mode: 0o600 });
+}
+/** Where the plain-text copy of a remote specification is kept for agents to read. */
+export function remoteOpenApiCopyPath(root, url, content) {
+    const json = content !== undefined ? content.trimStart().startsWith('{') : /\.json(?:$|[?#])/i.test(url);
+    return join(root, OPENAPI_CACHE_DIRECTORY, `${createHash('sha256').update(url).digest('hex')}.spec.${json ? 'json' : 'yaml'}`);
+}
+/** Make sure a remote specification has a readable local copy; returns its path, or undefined for local specs. */
+export async function ensureRemoteOpenApiCopy(root, source) {
+    if (!isSpecUrl(source.path))
+        return undefined;
+    const cached = await readRemoteCache(root, source.path);
+    if (cached) {
+        const copy = remoteOpenApiCopyPath(root, source.path, cached.content);
+        if (!(await pathExists(copy)))
+            await writeFile(copy, cached.content, { encoding: 'utf8', mode: 0o600 });
+        return copy;
+    }
+    const loaded = await loadOpenApiSource(root, source);
+    return remoteOpenApiCopyPath(root, source.path, loaded.content);
+}
+function remoteCachePath(root, url) {
+    return join(root, OPENAPI_CACHE_DIRECTORY, `${createHash('sha256').update(url).digest('hex')}.json`);
+}
+function formatBytes(value) { return `${Math.round(value / 1024 / 1024)} MB`; }
+function record(value) { return isRecord(value) ? value : {}; }
+function isRecord(value) { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); }
+function array(value) { return Array.isArray(value) ? value : []; }
+function text(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+const OPERATION_LABEL = /^(get|put|post|delete|patch|options|head|trace)\s+(\/\S*)/i;
+/**
+ * The part of a contract one citation names: an operation (`POST /users`,
+ * also reached through an error label such as `POST /users 422`), a schema,
+ * or a security scheme, with every component it references inlined below it
+ * so the writer sees request and response bodies without opening the spec.
+ * A citation that names nothing specific gets the contract's index instead.
+ */
+export function openApiExcerpt(document, citation, budget) {
+    const components = record(document.components);
+    const definitions = record(document.definitions);
+    const selected = {};
+    const wanted = [citation.label, citation.path].filter((value) => Boolean(value?.trim())).map((value) => value.trim());
+    for (const value of wanted) {
+        const operation = OPERATION_LABEL.exec(value);
+        if (operation) {
+            const item = record(record(document.paths)[operation[2]])[operation[1].toLowerCase()];
+            if (isRecord(item)) {
+                selected[`${operation[1].toUpperCase()} ${operation[2]}`] = item;
+                break;
+            }
+        }
+        const name = value.replace(/^(?:Schema |schema:)/, '');
+        const schema = record(components.schemas)[name] ?? definitions[name];
+        if (isRecord(schema)) {
+            selected[`Schema ${name}`] = schema;
+            break;
+        }
+        const scheme = record(components.securitySchemes)[name] ?? record(document.securityDefinitions)[name];
+        if (isRecord(scheme)) {
+            selected[`Security scheme ${name}`] = scheme;
+            break;
+        }
+    }
+    if (Object.keys(selected).length === 0) {
+        const index = {
+            info: document.info,
+            servers: document.servers ?? (document.host ? [`${document.host}${text(document.basePath) ?? ''}`] : undefined),
+            security: document.security,
+            securitySchemes: components.securitySchemes ?? document.securityDefinitions,
+            operations: Object.fromEntries(Object.entries(record(document.paths)).flatMap(([path, item]) => METHODS.filter((method) => isRecord(record(item)[method])).map((method) => [`${method.toUpperCase()} ${path}`, text(record(record(item)[method]).summary) ?? '']))),
+        };
+        return clip(stringifyYaml(index, { lineWidth: 0 }), budget);
+    }
+    // Inline referenced components, breadth first, until the budget is spent.
+    const referenced = {};
+    const queue = [...collectRefs(selected)];
+    while (queue.length > 0 && Object.keys(referenced).length < 40) {
+        const ref = queue.shift();
+        if (ref in referenced)
+            continue;
+        const target = ref.replace(/^#\//, '').split('/').reduce((node, key) => record(node)[key.replace(/~1/g, '/').replace(/~0/g, '~')], document);
+        if (target === undefined)
+            continue;
+        referenced[ref] = target;
+        queue.push(...collectRefs(target));
+    }
+    const body = { ...selected, ...(Object.keys(referenced).length > 0 ? { 'Referenced components': referenced } : {}) };
+    return clip(stringifyYaml(body, { lineWidth: 0 }), budget);
+}
+function collectRefs(value, found = new Set()) {
+    if (Array.isArray(value))
+        for (const item of value)
+            collectRefs(item, found);
+    else if (isRecord(value))
+        for (const [key, item] of Object.entries(value)) {
+            if (key === '$ref' && typeof item === 'string' && item.startsWith('#/'))
+                found.add(item);
+            else
+                collectRefs(item, found);
+        }
+    return found;
+}
+function clip(value, budget) {
+    if (value.length <= budget)
+        return { text: value, truncated: false };
+    const cut = value.slice(0, budget);
+    return { text: cut.slice(0, Math.max(cut.lastIndexOf('\n'), budget - 200)), truncated: true };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/page-editor-bridge.d.ts

@@ -0,0 +1,3 @@
+/** Runs inside the isolated editor iframe. Keep this function self-contained. */
+export declare function installPageEditorBridge(): void;
+//# sourceMappingURL=page-editor-bridge.d.ts.map

package/dist/page-editor-bridge.js

@@ -0,0 +1,109 @@
+/** Runs inside the isolated editor iframe. Keep this function self-contained. */
+export function installPageEditorBridge() {
+    const originals = new WeakMap();
+    const elements = [...document.querySelectorAll('[data-edit-start]')];
+    const linkLabels = [];
+    const children = (node) => [...node.childNodes].map(serialize).join('');
+    function serialize(node) {
+        if (node.nodeType === Node.TEXT_NODE)
+            return (node.textContent ?? '').replaceAll('\u00a0', ' ');
+        if (!(node instanceof HTMLElement))
+            return '';
+        const original = originals.get(node);
+        if (original && node.innerHTML === original.html)
+            return original.markdown;
+        if (node.dataset.mdAtom !== undefined)
+            return node.dataset.mdAtom;
+        const text = children(node);
+        switch (node.tagName) {
+            case 'STRONG':
+            case 'B': return text ? `**${text}**` : '';
+            case 'EM':
+            case 'I': return text ? `*${text}*` : '';
+            case 'S':
+            case 'STRIKE': return text ? `~~${text}~~` : '';
+            case 'CODE': return text ? '`' + (node.textContent ?? '') + '`' : '';
+            case 'A': return '[' + text + (node.dataset.mdSuffix ?? `](${node.getAttribute('href') ?? ''})`);
+            case 'BR': return '\n';
+            case 'DIV':
+            case 'P': return (node.previousSibling ? '\n' : '') + text;
+            default: return text;
+        }
+    }
+    const publish = (el) => {
+        let text;
+        const original = originals.get(el);
+        if (original && el.innerHTML === original.html)
+            text = original.markdown;
+        else if (el.dataset.editFormat === 'yaml')
+            text = JSON.stringify(el.innerText.replace(/\n/g, ' '));
+        else if (el.dataset.editFormat === 'plain')
+            text = el.innerText;
+        else
+            text = children(el).replace(/\n/g, ' ');
+        // Preserve the document's line-ending convention when editing fenced code.
+        if (el.dataset.editSource?.includes('\r\n'))
+            text = text.replace(/\r?\n/g, '\r\n');
+        parent.postMessage({ type: 'doxloop:edit-block', start: Number(el.dataset.editStart), end: Number(el.dataset.editEnd), text }, '*');
+    };
+    elements.forEach(el => {
+        const plain = el.dataset.editFormat !== 'markdown';
+        // Give links a dedicated editing host. Chromium otherwise moves the caret
+        // outside the anchor after replacing its label's final character.
+        el.querySelectorAll('a').forEach(link => {
+            const label = document.createElement('span');
+            label.dataset.editLinkLabel = '';
+            label.contentEditable = 'true';
+            link.contentEditable = 'false';
+            while (link.firstChild)
+                label.append(link.firstChild);
+            link.append(label);
+            linkLabels.push(label);
+        });
+        el.contentEditable = plain ? 'plaintext-only' : 'true';
+        el.setAttribute('role', 'textbox');
+        el.setAttribute('aria-label', 'Edit ' + (el.tagName === 'CODE' ? 'code' : /^H\d$/.test(el.tagName) ? 'heading' : el.tagName === 'LI' ? 'list item' : /^(TH|TD)$/.test(el.tagName) ? 'table cell' : 'paragraph'));
+        // Cache nested mark serialization so changing nearby words leaves their source intact.
+        Array.from(el.querySelectorAll('strong,em,s,code,a,[data-md-atom]')).reverse().forEach(node => {
+            originals.set(node, { html: node.innerHTML, markdown: serialize(node) });
+        });
+        originals.set(el, { html: el.innerHTML, markdown: el.dataset.editSource ?? '' });
+        el.addEventListener('input', () => publish(el));
+        el.addEventListener('beforeinput', event => {
+            const input = event;
+            if (el.dataset.editFormat !== 'plain' && (input.inputType === 'insertParagraph' || input.inputType === 'insertLineBreak')) {
+                // Each region owns one Markdown block; a newline must not split its list/table syntax.
+                event.preventDefault();
+                document.execCommand('insertText', false, ' ');
+            }
+        });
+        el.addEventListener('paste', event => {
+            event.preventDefault();
+            const text = event.clipboardData?.getData('text/plain') ?? '';
+            document.execCommand('insertText', false, el.dataset.editFormat === 'plain' ? text : text.replace(/\r?\n/g, ' '));
+        });
+        el.addEventListener('drop', event => event.preventDefault());
+    });
+    addEventListener('message', event => {
+        if (event.source === parent && event.data?.type === 'doxloop:editor-lock') {
+            linkLabels.forEach(label => { label.contentEditable = event.data.locked ? 'false' : 'true'; });
+            elements.forEach(el => { el.contentEditable = event.data.locked ? 'false' : el.dataset.editFormat !== 'markdown' ? 'plaintext-only' : 'true'; });
+        }
+    });
+    // Prevent selection/replacement across separate source regions.
+    document.addEventListener('beforeinput', event => {
+        const selection = getSelection();
+        const region = (node) => (node instanceof Element ? node : node?.parentElement)?.closest('[data-edit-start]');
+        if (selection && region(selection.anchorNode) !== region(selection.focusNode))
+            event.preventDefault();
+    });
+    document.addEventListener('click', event => { if (event.target.closest('a'))
+        event.preventDefault(); });
+    document.addEventListener('keydown', event => {
+        if ((event.metaKey || event.ctrlKey) && event.key === 's') {
+            event.preventDefault();
+            parent.postMessage({ type: 'doxloop:save-draft' }, '*');
+        }
+    });
+}
+//# sourceMappingURL=page-editor-bridge.js.map

package/dist/page-editor-preview.d.ts

@@ -0,0 +1,10 @@
+/** A sandboxed native rendering of a draft; this endpoint never writes a file. */
+export declare function pageEditorPreview(root: string, path: string, content: string, base: string): Promise<{
+    html: string;
+    blocks: {
+        start: number;
+        end: number;
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=page-editor-preview.d.ts.map