@walkthru-earth/objex 0.1.0

package/dist/utils/hex.d.ts

@@ -0,0 +1,10 @@
+export interface HexRow {
+    offset: string;
+    hex: string[];
+    ascii: string;
+}
+/**
+ * Generates a hex dump from binary data.
+ * Returns rows of offset | hex bytes | ASCII representation.
+ */
+export declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];

package/dist/utils/hex.js

@@ -0,0 +1,27 @@
+/**
+ * Generates a hex dump from binary data.
+ * Returns rows of offset | hex bytes | ASCII representation.
+ */
+export function generateHexDump(data, bytesPerRow = 16) {
+    const rows = [];
+    for (let i = 0; i < data.length; i += bytesPerRow) {
+        const slice = data.slice(i, i + bytesPerRow);
+        const offset = i.toString(16).padStart(8, '0');
+        const hex = [];
+        for (let j = 0; j < bytesPerRow; j++) {
+            if (j < slice.length) {
+                hex.push(slice[j].toString(16).padStart(2, '0'));
+            }
+            else {
+                hex.push('  ');
+            }
+        }
+        let ascii = '';
+        for (let j = 0; j < slice.length; j++) {
+            const byte = slice[j];
+            ascii += byte >= 0x20 && byte <= 0x7e ? String.fromCharCode(byte) : '.';
+        }
+        rows.push({ offset, hex, ascii });
+    }
+    return rows;
+}

package/dist/utils/host-detection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Auto-detect hosting bucket from URL search params and window.location.
+ *
+ * Detection priority:
+ * 1. `?url=<storage-url>` query parameter (highest priority)
+ * 2. `window.location.hostname` pattern matching (fallback)
+ *
+ * Also extracts `rootPrefix` when the app is hosted inside a subfolder.
+ */
+import type { StorageProvider } from './storage-url.js';
+export interface DetectedHost {
+    provider: StorageProvider;
+    bucket: string;
+    region: string;
+    endpoint: string;
+    rootPrefix: string;
+    bucketUrl: string;
+}
+/**
+ * Detect hosting bucket from current URL.
+ * Returns null when no hosting bucket can be determined.
+ */
+export declare function detectHostBucket(): DetectedHost | null;

package/dist/utils/host-detection.js

@@ -0,0 +1,289 @@
+/**
+ * Auto-detect hosting bucket from URL search params and window.location.
+ *
+ * Detection priority:
+ * 1. `?url=<storage-url>` query parameter (highest priority)
+ * 2. `window.location.hostname` pattern matching (fallback)
+ *
+ * Also extracts `rootPrefix` when the app is hosted inside a subfolder.
+ */
+import { parseStorageUrl } from './storage-url.js';
+/**
+ * Extract root prefix from pathname.
+ * When hosted at `/subfolder/index.html` or `/subfolder/`, returns `subfolder/`.
+ */
+function extractRootPrefix(pathname) {
+    // Strip trailing filename (index.html, etc.)
+    let clean = pathname.replace(/\/[^/]*\.[^/]*$/, '/');
+    // Remove leading slash
+    clean = clean.replace(/^\//, '');
+    // Empty or just '/' means no prefix
+    if (!clean || clean === '/')
+        return '';
+    // Ensure trailing slash
+    if (!clean.endsWith('/'))
+        clean += '/';
+    return clean;
+}
+/**
+ * Build a normalized API endpoint URL for a detected provider.
+ */
+function buildBucketUrl(provider, endpoint, bucket) {
+    if (endpoint) {
+        return `${endpoint.replace(/\/$/, '')}/${bucket}`;
+    }
+    switch (provider) {
+        case 'gcs':
+            return `https://storage.googleapis.com/${bucket}`;
+        case 'azure':
+            return `${endpoint}/${bucket}`;
+        case 'storj':
+            return `https://gateway.storjshare.io/${bucket}`;
+        default:
+            return `https://s3.us-east-1.amazonaws.com/${bucket}`;
+    }
+}
+/**
+ * Detect hosting bucket from current URL.
+ * Returns null when no hosting bucket can be determined.
+ */
+export function detectHostBucket() {
+    if (typeof window === 'undefined')
+        return null;
+    const url = new URL(window.location.href);
+    const host = url.hostname;
+    // --- Priority 1: ?url= query parameter ---
+    const urlParam = url.searchParams.get('url');
+    if (urlParam) {
+        const parsed = parseStorageUrl(urlParam);
+        if (parsed.bucket) {
+            return {
+                provider: parsed.provider === 'unknown' ? 's3' : parsed.provider,
+                bucket: parsed.bucket,
+                region: parsed.region,
+                endpoint: parsed.endpoint,
+                rootPrefix: '',
+                bucketUrl: buildBucketUrl(parsed.provider, parsed.endpoint, parsed.bucket)
+            };
+        }
+    }
+    // --- Priority 2: Hostname pattern matching ---
+    const pathname = url.pathname;
+    // AWS S3 virtual-hosted: <bucket>.s3.<region>.amazonaws.com
+    const awsVhost = host.match(/^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+    if (awsVhost) {
+        return {
+            provider: 's3',
+            bucket: awsVhost[1],
+            region: awsVhost[2],
+            endpoint: '',
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://s3.${awsVhost[2]}.amazonaws.com/${awsVhost[1]}`
+        };
+    }
+    // AWS S3 website hosting: <bucket>.s3-website-<region>.amazonaws.com or <bucket>.s3-website.<region>.amazonaws.com
+    const awsWebsite = host.match(/^(.+)\.s3-website[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+    if (awsWebsite) {
+        return {
+            provider: 's3',
+            bucket: awsWebsite[1],
+            region: awsWebsite[2],
+            endpoint: '',
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://s3.${awsWebsite[2]}.amazonaws.com/${awsWebsite[1]}`
+        };
+    }
+    // AWS S3 path-style: s3.<region>.amazonaws.com/<bucket>
+    const awsPath = host.match(/^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+    if (awsPath) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 's3',
+                bucket: parts[0],
+                region: awsPath[1],
+                endpoint: '',
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://s3.${awsPath[1]}.amazonaws.com/${parts[0]}`
+            };
+        }
+    }
+    // GCS: storage.googleapis.com/<bucket>
+    if (host === 'storage.googleapis.com') {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'gcs',
+                bucket: parts[0],
+                region: 'us',
+                endpoint: '',
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://storage.googleapis.com/${parts[0]}`
+            };
+        }
+    }
+    // GCS virtual-hosted: <bucket>.storage.googleapis.com
+    const gcsVhost = host.match(/^(.+)\.storage\.googleapis\.com$/);
+    if (gcsVhost) {
+        return {
+            provider: 'gcs',
+            bucket: gcsVhost[1],
+            region: 'us',
+            endpoint: '',
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://storage.googleapis.com/${gcsVhost[1]}`
+        };
+    }
+    // Azure Static Website: <account>.z<N>.web.core.windows.net
+    const azureWeb = host.match(/^([a-z0-9]+)\.z\d+\.web\.core\.windows\.net$/);
+    if (azureWeb) {
+        return {
+            provider: 'azure',
+            bucket: '$web',
+            region: '',
+            endpoint: `https://${azureWeb[1]}.blob.core.windows.net`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://${azureWeb[1]}.blob.core.windows.net/$web`
+        };
+    }
+    // Azure Blob: <account>.blob.core.windows.net/<container>
+    const azureBlob = host.match(/^([a-z0-9]+)\.blob\.core\.windows\.net$/);
+    if (azureBlob) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'azure',
+                bucket: parts[0],
+                region: '',
+                endpoint: `https://${host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://${host}/${parts[0]}`
+            };
+        }
+    }
+    // R2 public: pub-<id>.r2.dev
+    const r2Public = host.match(/^(pub-[a-z0-9]+)\.r2\.dev$/);
+    if (r2Public) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        return {
+            provider: 'r2',
+            bucket: parts[0] || r2Public[1],
+            region: 'auto',
+            endpoint: `https://${host}`,
+            rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+            bucketUrl: `https://${host}`
+        };
+    }
+    // DigitalOcean Spaces: <bucket>.<region>.digitaloceanspaces.com
+    const doSpaces = host.match(/^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/);
+    if (doSpaces) {
+        return {
+            provider: 's3',
+            bucket: doSpaces[1],
+            region: doSpaces[2],
+            endpoint: `https://${doSpaces[2]}.digitaloceanspaces.com`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://${doSpaces[2]}.digitaloceanspaces.com/${doSpaces[1]}`
+        };
+    }
+    // DigitalOcean Spaces CDN: <bucket>.<region>.cdn.digitaloceanspaces.com
+    const doCdn = host.match(/^(.+)\.([a-z0-9-]+)\.cdn\.digitaloceanspaces\.com$/);
+    if (doCdn) {
+        return {
+            provider: 's3',
+            bucket: doCdn[1],
+            region: doCdn[2],
+            endpoint: `https://${doCdn[2]}.digitaloceanspaces.com`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://${doCdn[2]}.digitaloceanspaces.com/${doCdn[1]}`
+        };
+    }
+    // Wasabi: s3.<region>.wasabisys.com/<bucket>
+    const wasabi = host.match(/^s3\.([a-z0-9-]+)\.wasabisys\.com$/);
+    if (wasabi) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 's3',
+                bucket: parts[0],
+                region: wasabi[1],
+                endpoint: `https://${host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://${host}/${parts[0]}`
+            };
+        }
+    }
+    // B2 S3: <bucket>.s3.<region>.backblazeb2.com
+    const b2s3 = host.match(/^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/);
+    if (b2s3) {
+        return {
+            provider: 's3',
+            bucket: b2s3[1],
+            region: b2s3[2],
+            endpoint: `https://s3.${b2s3[2]}.backblazeb2.com`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://s3.${b2s3[2]}.backblazeb2.com/${b2s3[1]}`
+        };
+    }
+    // IBM COS: <bucket>.s3-web.<region>.cloud-object-storage.appdomain.cloud
+    const ibmCos = host.match(/^(.+)\.s3-web\.([a-z0-9-]+)\.cloud-object-storage\.appdomain\.cloud$/);
+    if (ibmCos) {
+        return {
+            provider: 's3',
+            bucket: ibmCos[1],
+            region: ibmCos[2],
+            endpoint: `https://s3.${ibmCos[2]}.cloud-object-storage.appdomain.cloud`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://s3.${ibmCos[2]}.cloud-object-storage.appdomain.cloud/${ibmCos[1]}`
+        };
+    }
+    // Storj S3 gateway: gateway.storjshare.io/<bucket> (or gateway.<region>.storjshare.io)
+    const storjGateway = host.match(/^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+    if (storjGateway) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'storj',
+                bucket: parts[0],
+                region: storjGateway[1] || 'us1',
+                endpoint: `${url.protocol}//${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
+            };
+        }
+    }
+    // Storj linksharing: link.storjshare.io/raw/<access>/<bucket>/...
+    const storjLink = host.match(/^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+    if (storjLink) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length >= 3 && (parts[0] === 'raw' || parts[0] === 's')) {
+            return {
+                provider: 'storj',
+                bucket: parts[2],
+                region: storjLink[1] || 'us1',
+                endpoint: `${url.protocol}//${url.host}/${parts[0]}/${parts[1]}`,
+                rootPrefix: parts.length > 3 ? extractRootPrefix(`/${parts.slice(3).join('/')}`) : '',
+                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}/${parts[1]}/${parts[2]}`
+            };
+        }
+    }
+    // MinIO / localhost / private IPs
+    const isLocal = host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host.startsWith('192.168.') ||
+        host.startsWith('10.');
+    if (isLocal) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'minio',
+                bucket: parts[0],
+                region: 'us-east-1',
+                endpoint: `${url.protocol}//${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
+            };
+        }
+    }
+    return null;
+}

package/dist/utils/map-selection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared selection highlight for all map viewers.
+ *
+ * Adds a MapLibre GeoJSON source + yellow outline layers that render
+ * on top of any data layer (deck.gl or native MapLibre).
+ * Works because every viewer uses MapLibre as its base map.
+ */
+import type maplibregl from 'maplibre-gl';
+/** Add an empty GeoJSON source + outline layers to the map. Call once in onMapReady. */
+export declare function setupSelectionLayer(map: maplibregl.Map): void;
+/** Set or clear the selected feature. Pass null to clear. */
+export declare function updateSelection(map: maplibregl.Map, feature: GeoJSON.Feature | null): void;

package/dist/utils/map-selection.js

@@ -0,0 +1,45 @@
+const SOURCE_ID = 'selection-highlight';
+const SELECTION_COLOR = '#ffc800'; // QGIS-style yellow
+/** Add an empty GeoJSON source + outline layers to the map. Call once in onMapReady. */
+export function setupSelectionLayer(map) {
+    if (map.getSource(SOURCE_ID))
+        return; // idempotent
+    map.addSource(SOURCE_ID, {
+        type: 'geojson',
+        data: { type: 'FeatureCollection', features: [] }
+    });
+    // Polygon / line outline
+    map.addLayer({
+        id: 'selection-outline',
+        type: 'line',
+        source: SOURCE_ID,
+        paint: {
+            'line-color': SELECTION_COLOR,
+            'line-width': 3,
+            'line-opacity': 1
+        }
+    });
+    // Point halo
+    map.addLayer({
+        id: 'selection-point',
+        type: 'circle',
+        source: SOURCE_ID,
+        filter: ['==', '$type', 'Point'],
+        paint: {
+            'circle-radius': 10,
+            'circle-color': 'transparent',
+            'circle-stroke-color': SELECTION_COLOR,
+            'circle-stroke-width': 3
+        }
+    });
+}
+/** Set or clear the selected feature. Pass null to clear. */
+export function updateSelection(map, feature) {
+    const source = map.getSource(SOURCE_ID);
+    if (!source)
+        return;
+    source.setData({
+        type: 'FeatureCollection',
+        features: feature ? [feature] : []
+    });
+}

package/dist/utils/markdown-sql.d.ts

@@ -0,0 +1,30 @@
+export interface SqlBlock {
+    name: string;
+    sql: string;
+    startLine: number;
+    endLine: number;
+}
+export interface ParsedMarkdownDocument {
+    frontmatter: Record<string, any>;
+    content: string;
+    sqlBlocks: SqlBlock[];
+}
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+export declare function parseMarkdownDocument(markdown: string): ParsedMarkdownDocument;
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+export declare function interpolateTemplates(text: string, queryResults: Map<string, Record<string, any>[]>): string;
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+export declare function markSqlBlocks(content: string): string;

package/dist/utils/markdown-sql.js

@@ -0,0 +1,73 @@
+import YAML from 'yaml';
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+export function parseMarkdownDocument(markdown) {
+    let frontmatter = {};
+    let content = markdown;
+    // Extract YAML frontmatter
+    const fmMatch = markdown.match(/^---\n([\s\S]*?)\n---\n/);
+    if (fmMatch) {
+        try {
+            frontmatter = YAML.parse(fmMatch[1]) || {};
+        }
+        catch {
+            // Invalid YAML — ignore
+        }
+        content = markdown.slice(fmMatch[0].length);
+    }
+    // Extract SQL blocks
+    const sqlBlocks = [];
+    const lines = content.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const match = line.match(/^```sql\s+(\w[\w-]*)\s*$/);
+        if (match) {
+            const name = match[1];
+            const startLine = i;
+            const sqlLines = [];
+            i++;
+            while (i < lines.length && lines[i] !== '```') {
+                sqlLines.push(lines[i]);
+                i++;
+            }
+            sqlBlocks.push({
+                name,
+                sql: sqlLines.join('\n'),
+                startLine,
+                endLine: i
+            });
+        }
+        i++;
+    }
+    return { frontmatter, content, sqlBlocks };
+}
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+export function interpolateTemplates(text, queryResults) {
+    return text.replace(/\{(\w+)\.rows\[(\d+)\]\.(\w+)\}/g, (match, queryName, rowIdx, colName) => {
+        const rows = queryResults.get(queryName);
+        if (!rows)
+            return match;
+        const row = rows[parseInt(rowIdx, 10)];
+        if (!row)
+            return match;
+        const value = row[colName];
+        return value !== undefined ? String(value) : match;
+    });
+}
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+export function markSqlBlocks(content) {
+    return content.replace(/```sql\s+(\w[\w-]*)\s*\n([\s\S]*?)```/g, (_, name) => `<div data-sql-block="${name}"></div>`);
+}

package/dist/utils/markdown.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Renders markdown to HTML with GFM support.
+ * Code blocks use reversed Shiki theme (dark on light, light on dark)
+ * and include a copy button.
+ */
+export declare function renderMarkdown(markdown: string): Promise<string>;
+/**
+ * Detect whether text is primarily RTL by sampling the first 1000 characters.
+ */
+export declare function detectRTL(text: string): boolean;
+/**
+ * Post-process rendered HTML for RTL/LTR direction.
+ * Uses DOM-based approach for reliable mixed content handling.
+ * Code blocks always get LTR. In RTL docs, individual block elements
+ * get direction based on their content language.
+ * Western digits (0-9) are LTR, Arabic-Indic digits (٠-٩) are RTL.
+ */
+export declare function processDirection(html: string, isRTL: boolean): string;

package/dist/utils/markdown.js

@@ -0,0 +1,146 @@
+import { Marked } from 'marked';
+import { extensionToShikiLang, highlightCodeReversed } from './shiki';
+let markedInstance = null;
+function getMarked() {
+    if (markedInstance)
+        return markedInstance;
+    markedInstance = new Marked({
+        async: true,
+        gfm: true,
+        breaks: false
+    });
+    markedInstance.use({
+        renderer: {
+            code({ text, lang }) {
+                const escaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+                if (lang === 'mermaid') {
+                    return `<div class="mermaid">${escaped}</div>`;
+                }
+                return `<pre class="shiki-pending" data-lang="${lang || ''}" data-code="${encodeURIComponent(text)}"><code>${escaped}</code></pre>`;
+            }
+        }
+    });
+    return markedInstance;
+}
+/**
+ * Renders markdown to HTML with GFM support.
+ * Code blocks use reversed Shiki theme (dark on light, light on dark)
+ * and include a copy button.
+ */
+export async function renderMarkdown(markdown) {
+    const marked = getMarked();
+    let html = await marked.parse(markdown);
+    // Post-process: highlight code blocks with Shiki (reversed theme)
+    const codeBlockRegex = /<pre class="shiki-pending" data-lang="([^"]*)" data-code="([^"]*)"><code>[\s\S]*?<\/code><\/pre>/g;
+    const matches = [...html.matchAll(codeBlockRegex)];
+    for (const match of matches) {
+        const lang = match[1];
+        const code = decodeURIComponent(match[2]);
+        const shikiLang = lang ? (extensionToShikiLang(`.${lang}`) ?? lang) : undefined;
+        try {
+            const highlighted = await highlightCodeReversed(code, shikiLang);
+            // Wrap in a container with copy button
+            const langLabel = lang ? `<span class="code-lang">${lang}</span>` : '';
+            const copyBtn = `<button class="code-copy-btn" data-code="${encodeURIComponent(code)}" title="Copy">${langLabel}<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button>`;
+            const wrapped = `<div class="code-block-wrapper">${copyBtn}${highlighted}</div>`;
+            html = html.replace(match[0], wrapped);
+        }
+        catch {
+            // If highlighting fails, keep the escaped version
+        }
+    }
+    return html;
+}
+// RTL unicode ranges: Arabic, Hebrew, Arabic Supplement, Arabic Extended
+const RTL_CHAR_REGEX = /[\u0590-\u05FF\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/;
+// Arabic-Indic digits: ٠١٢٣٤٥٦٧٨٩ and Extended Arabic-Indic: ۰۱۲۳۴۵۶۷۸۹
+const ARABIC_DIGIT_REGEX = /[\u0660-\u0669\u06F0-\u06F9]/;
+// Western digits
+const WESTERN_DIGIT_REGEX = /[0-9]/;
+/**
+ * Detect whether text is primarily RTL by sampling the first 1000 characters.
+ */
+export function detectRTL(text) {
+    const sample = text.slice(0, 1000);
+    let rtlCount = 0;
+    for (const char of sample) {
+        if (RTL_CHAR_REGEX.test(char))
+            rtlCount++;
+    }
+    return rtlCount > 5;
+}
+/**
+ * Determine if a text segment should be LTR.
+ * - Text with Latin first strong char and more Latin than Arabic → LTR
+ * - Text with only Western digits (0-9) and no Arabic chars → LTR
+ * - Text with Arabic-Indic digits (٠-٩) → RTL
+ * - Text with Arabic first strong char → RTL
+ */
+function shouldBeLTR(text) {
+    if (!text)
+        return false;
+    // Find the first strong directional character (Arabic or Latin)
+    const match = text.match(/[\u0600-\u06FFa-zA-Z]/);
+    if (match) {
+        // Has strong directional characters
+        if (/[a-zA-Z]/.test(match[0])) {
+            // First strong char is Latin — confirm with count
+            const arabicCount = (text.match(/[\u0600-\u06FF]/g) || []).length;
+            const englishCount = (text.match(/[a-zA-Z]/g) || []).length;
+            return englishCount > arabicCount;
+        }
+        // First strong char is Arabic → RTL
+        return false;
+    }
+    // No strong directional chars — check digits
+    const hasWesternDigits = WESTERN_DIGIT_REGEX.test(text);
+    const hasArabicDigits = ARABIC_DIGIT_REGEX.test(text);
+    if (hasArabicDigits)
+        return false; // Arabic-Indic digits → RTL
+    if (hasWesternDigits)
+        return true; // Western digits → LTR
+    // No directional content at all — inherit parent direction
+    return false;
+}
+/**
+ * Post-process rendered HTML for RTL/LTR direction.
+ * Uses DOM-based approach for reliable mixed content handling.
+ * Code blocks always get LTR. In RTL docs, individual block elements
+ * get direction based on their content language.
+ * Western digits (0-9) are LTR, Arabic-Indic digits (٠-٩) are RTL.
+ */
+export function processDirection(html, isRTL) {
+    if (typeof document === 'undefined')
+        return html;
+    if (!isRTL)
+        return html;
+    const container = document.createElement('div');
+    container.innerHTML = html;
+    // Code blocks are always LTR
+    for (const el of container.querySelectorAll('pre, code')) {
+        el.style.direction = 'ltr';
+        el.style.textAlign = 'left';
+    }
+    // Process each block element for mixed content
+    for (const el of container.querySelectorAll('p, li, h1, h2, h3, h4, h5, h6, td, th')) {
+        const text = el.textContent || '';
+        if (shouldBeLTR(text)) {
+            el.style.direction = 'ltr';
+            el.style.textAlign = 'left';
+            // For lists in RTL context with LTR content, swap padding
+            if (el.tagName === 'LI') {
+                const parent = el.parentElement;
+                if (parent && (parent.tagName === 'UL' || parent.tagName === 'OL')) {
+                    parent.style.paddingLeft = '2em';
+                    parent.style.paddingRight = '0';
+                }
+            }
+        }
+        else {
+            // Explicitly set RTL direction on Arabic content
+            el.style.direction = 'rtl';
+            el.style.textAlign = 'right';
+        }
+    }
+    return container.innerHTML;
+}