omni-viewer-core 0.1.0

package/dist/viewers/hwp/controller.js

@@ -0,0 +1,22 @@
+export const HWP_MIN_ZOOM = 0.25;
+export const HWP_MAX_ZOOM = 2.5;
+export const HWP_ZOOM_STEP = 0.1;
+export function createHwpController() {
+    let zoom = 1;
+    const listeners = new Set();
+    const snapshot = () => ({ zoom });
+    const emit = () => listeners.forEach((listener) => listener(snapshot()));
+    return {
+        get state() { return snapshot(); },
+        dispatch(action) {
+            if (action.type === 'zoom-in')
+                zoom = Math.min(HWP_MAX_ZOOM, Math.round((zoom + HWP_ZOOM_STEP) * 100) / 100);
+            if (action.type === 'zoom-out')
+                zoom = Math.max(HWP_MIN_ZOOM, Math.round((zoom - HWP_ZOOM_STEP) * 100) / 100);
+            if (action.type === 'reset-zoom')
+                zoom = 1;
+            emit();
+        },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); }
+    };
+}

package/dist/viewers/hwp/index.d.ts

@@ -0,0 +1,39 @@
+import type { HostContext } from '../../host/index.js';
+import { type MountOptions, type ViewerHandle, type ViewerInput } from '../types.js';
+import { type HwpController } from './controller.js';
+export * from './controller.js';
+export { hwpViewerCss } from './styles.js';
+export declare const HWP_VIEWER_META: {
+    id: string;
+    displayNameKey: string;
+    extensions: string[];
+    priority: number;
+    requiredServices: readonly [];
+    optionalServices: readonly [];
+    inputOwnership: "consumes";
+};
+export declare const HWP_MAX_INPUT_BYTES: number;
+export declare const HWP_MAX_RENDERED_PAGES = 100;
+export declare const SUPPORTED_DEPENDENCY_VERSIONS: {
+    readonly rhwp: "0.7.3";
+};
+export interface RhwpDocument {
+    pageCount(): number;
+    renderPageSvg(pageIndex: number): string;
+    free?(): void;
+}
+export interface RhwpModule {
+    HwpDocument: new (data: Uint8Array) => RhwpDocument;
+}
+export interface HwpViewerDeps {
+    loadRhwp(): Promise<RhwpModule>;
+}
+export interface HwpViewerHandle extends ViewerHandle {
+    readonly controller: HwpController;
+}
+export declare class HwpViewerError extends Error {
+    readonly code: 'missing-dependency' | 'invalid-format' | 'corrupted' | 'limit-exceeded';
+    readonly messageKey: string;
+    constructor(code: 'missing-dependency' | 'invalid-format' | 'corrupted' | 'limit-exceeded', messageKey: string, options?: ErrorOptions);
+}
+export declare function mountHwpViewer(input: ViewerInput, container: HTMLElement, ctx: HostContext, deps?: Partial<HwpViewerDeps>, options?: MountOptions): Promise<HwpViewerHandle>;

package/dist/viewers/hwp/index.js

@@ -0,0 +1,271 @@
+import { MountAbortedError, VIEWER_ROOT_CLASS } from '../types.js';
+import { createHwpController } from './controller.js';
+import { hwpViewerCss } from './styles.js';
+export * from './controller.js';
+export { hwpViewerCss } from './styles.js';
+export const HWP_VIEWER_META = { id: 'hwp', displayNameKey: 'hwp.title', extensions: ['hwp', 'hwpx'], priority: 15, requiredServices: [], optionalServices: [], inputOwnership: 'consumes' };
+export const HWP_MAX_INPUT_BYTES = 50 * 1024 * 1024;
+export const HWP_MAX_RENDERED_PAGES = 100;
+export const SUPPORTED_DEPENDENCY_VERSIONS = { rhwp: '0.7.3' };
+export class HwpViewerError extends Error {
+    code;
+    messageKey;
+    constructor(code, messageKey, options) {
+        super(messageKey, options);
+        this.code = code;
+        this.messageKey = messageKey;
+        this.name = 'HwpViewerError';
+    }
+}
+const el = (tag, cls, text) => {
+    const node = document.createElement(tag);
+    if (cls)
+        node.className = cls;
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+};
+let activeKeyboardOwner;
+const measureTarget = globalThis;
+let measureUsers = 0;
+let originalMeasure;
+let sharedMeasure;
+function installMeasureTextWidth() {
+    if (measureUsers++ > 0)
+        return releaseMeasureTextWidth;
+    originalMeasure = measureTarget.measureTextWidth;
+    const canvas = document.createElement('canvas');
+    const context = canvas.getContext('2d');
+    sharedMeasure = (font, text) => {
+        if (!context)
+            return String(text ?? '').length * 10;
+        context.font = font || '10px sans-serif';
+        return context.measureText(String(text ?? '')).width;
+    };
+    measureTarget.measureTextWidth = sharedMeasure;
+    return releaseMeasureTextWidth;
+}
+function releaseMeasureTextWidth() {
+    if (measureUsers === 0 || --measureUsers > 0)
+        return;
+    if (originalMeasure)
+        measureTarget.measureTextWidth = originalMeasure;
+    else
+        delete measureTarget.measureTextWidth;
+    originalMeasure = undefined;
+    sharedMeasure = undefined;
+}
+function svgElement(markup) {
+    const parsed = new DOMParser().parseFromString(markup, 'image/svg+xml');
+    const svg = parsed.documentElement;
+    if (svg.localName !== 'svg' || parsed.querySelector('parsererror'))
+        throw new HwpViewerError('corrupted', 'diag.hwp.corrupted');
+    sanitizeSvg(svg);
+    return document.importNode(svg, true);
+}
+const FORBIDDEN_SVG_ELEMENTS = new Set(['script', 'style', 'foreignobject', 'iframe', 'object', 'embed', 'audio', 'video', 'animate', 'animatemotion', 'animatetransform', 'set', 'mpath']);
+const URL_ATTRIBUTES = new Set(['href', 'src', 'action', 'formaction', 'poster']);
+const LOCAL_URL_PATTERN = /^url\(\s*(['"]?)#[A-Za-z_][\w:.-]*\1\s*\)$/i;
+const LOCAL_FRAGMENT_PATTERN = /^#[A-Za-z_][\w:.-]*$/;
+// rhwp 0.7.3 emits embedded raster pictures as data URIs. SVG is deliberately
+// excluded because it can carry active content. TIFF is safe to retain but may
+// remain undecodable on browsers without native TIFF support.
+const SAFE_RASTER_DATA_PATTERN = /^data:image\/(?:png|jpe?g|gif|webp|bmp|x-bmp|x-ms-bmp|tiff);base64,[a-z0-9+/=\s]+$/i;
+/** Fixed core policy for SVG derived from untrusted document bytes (ADR 25). */
+function sanitizeSvg(root) {
+    for (const node of [root, ...root.querySelectorAll('*')]) {
+        if (FORBIDDEN_SVG_ELEMENTS.has(node.localName.toLowerCase())) {
+            node.remove();
+            continue;
+        }
+        for (const attribute of [...node.attributes]) {
+            const name = attribute.localName.toLowerCase();
+            const value = attribute.value.trim();
+            if (name.startsWith('on') || name === 'srcdoc') {
+                node.removeAttributeNode(attribute);
+                continue;
+            }
+            if (name === 'style') {
+                if (!isSafeSvgStyle(value))
+                    node.removeAttributeNode(attribute);
+                continue;
+            }
+            if (URL_ATTRIBUTES.has(name) || name === 'xlink:href') {
+                const localReference = LOCAL_FRAGMENT_PATTERN.test(value);
+                const rasterImage = node.localName.toLowerCase() === 'image' && SAFE_RASTER_DATA_PATTERN.test(value);
+                if (!localReference && !rasterImage)
+                    node.removeAttributeNode(attribute);
+                continue;
+            }
+            if (/url\s*\(/i.test(value) && !LOCAL_URL_PATTERN.test(value))
+                node.removeAttributeNode(attribute);
+        }
+    }
+}
+function isSafeSvgStyle(style) {
+    if (/@import|expression\s*\(|javascript\s*:|data\s*:/i.test(style))
+        return false;
+    const urls = style.match(/url\([^)]*\)/gi) ?? [];
+    return urls.every((url) => LOCAL_URL_PATTERN.test(url));
+}
+export async function mountHwpViewer(input, container, ctx, deps = {}, options = {}) {
+    if (options.signal?.aborted)
+        throw new MountAbortedError();
+    if (input.data.byteLength > HWP_MAX_INPUT_BYTES)
+        throw new HwpViewerError('limit-exceeded', 'diag.hwp.limit-exceeded');
+    const root = options.styleIsolation !== 'scoped' && typeof container.attachShadow === 'function' ? (container.shadowRoot ?? container.attachShadow({ mode: 'open' })) : container;
+    root.replaceChildren();
+    let ownedStyle;
+    if (root === container)
+        container.classList.add(VIEWER_ROOT_CLASS, 'omni-viewer--hwp');
+    else {
+        ownedStyle = el('style');
+        ownedStyle.textContent = hwpViewerCss;
+        root.append(ownedStyle);
+    }
+    const frame = el('section', 'omni-hwp');
+    const header = el('header', 'omni-hwp__header');
+    const title = el('span', 'omni-hwp__title', `📄 ${input.fileName}`);
+    const meta = el('span', 'omni-hwp__meta', `${formatBytes(input.data.byteLength)} · ${input.fileName.toLowerCase().endsWith('.hwpx') ? 'HWPX' : 'HWP'}`);
+    header.append(title, meta);
+    const toolbar = el('div', 'omni-hwp__toolbar');
+    const out = el('button', undefined, '−'), level = el('span', 'omni-hwp__zoom', '100%'), inc = el('button', undefined, '+'), reset = el('button', undefined, ctx.i18n.t('hwp.reset'));
+    out.type = inc.type = reset.type = 'button';
+    out.setAttribute('aria-label', ctx.i18n.t('hwp.zoomOut'));
+    inc.setAttribute('aria-label', ctx.i18n.t('hwp.zoomIn'));
+    reset.setAttribute('aria-label', ctx.i18n.t('hwp.reset'));
+    toolbar.append(out, level, inc, reset);
+    const viewport = el('main', 'omni-hwp__viewport');
+    const content = el('div', 'omni-hwp__content');
+    content.setAttribute('role', 'document');
+    const loading = el('div', 'omni-hwp__status omni-hwp__loading', ctx.i18n.t('hwp.loading'));
+    viewport.append(content, loading);
+    frame.append(header, toolbar, viewport);
+    root.append(frame);
+    const controller = createHwpController();
+    const disposers = [];
+    const restoreMeasure = installMeasureTextWidth();
+    let rhwpDocument;
+    let cleaned = false;
+    let loadedRhwp;
+    const keyboardOwner = {};
+    activeKeyboardOwner = keyboardOwner;
+    const freeDocument = () => { const current = rhwpDocument; rhwpDocument = undefined; current?.free?.(); };
+    const cleanup = () => { if (cleaned)
+        return; cleaned = true; if (activeKeyboardOwner === keyboardOwner)
+        activeKeyboardOwner = undefined; off(); disposers.forEach((dispose) => dispose()); freeDocument(); restoreMeasure(); frame.remove(); ownedStyle?.remove(); if (root === container)
+        container.classList.remove(VIEWER_ROOT_CLASS, 'omni-viewer--hwp'); };
+    const listen = (target, name, fn, listenerOptions) => { target.addEventListener(name, fn, listenerOptions); disposers.push(() => target.removeEventListener(name, fn, listenerOptions)); };
+    const off = controller.subscribe((state) => { content.style.transform = `scale(${state.zoom})`; level.textContent = `${Math.round(state.zoom * 100)}%`; });
+    listen(out, 'click', () => controller.dispatch({ type: 'zoom-out' }));
+    listen(inc, 'click', () => controller.dispatch({ type: 'zoom-in' }));
+    listen(reset, 'click', () => controller.dispatch({ type: 'reset-zoom' }));
+    listen(frame, 'pointerdown', () => { activeKeyboardOwner = keyboardOwner; });
+    listen(frame, 'focusin', () => { activeKeyboardOwner = keyboardOwner; });
+    listen(document, 'keydown', ((event) => { if (activeKeyboardOwner !== keyboardOwner || !(event.ctrlKey || event.metaKey))
+        return; if (event.key === '+' || event.key === '=')
+        controller.dispatch({ type: 'zoom-in' });
+    else if (event.key === '-')
+        controller.dispatch({ type: 'zoom-out' });
+    else if (event.key === '0')
+        controller.dispatch({ type: 'reset-zoom' });
+    else
+        return; event.preventDefault(); }));
+    listen(viewport, 'wheel', ((event) => { if (!(event.ctrlKey || event.metaKey))
+        return; event.preventDefault(); controller.dispatch({ type: event.deltaY < 0 ? 'zoom-in' : 'zoom-out' }); }), { passive: false });
+    try {
+        if (!deps.loadRhwp)
+            throw new HwpViewerError('missing-dependency', 'diag.hwp.missing-dependency');
+        try {
+            loadedRhwp = await deps.loadRhwp();
+        }
+        catch (cause) {
+            throw new HwpViewerError('missing-dependency', 'diag.hwp.missing-dependency', { cause });
+        }
+        if (options.signal?.aborted)
+            throw new MountAbortedError();
+        try {
+            rhwpDocument = new loadedRhwp.HwpDocument(input.data);
+        }
+        catch (cause) {
+            throw new HwpViewerError('invalid-format', 'diag.hwp.invalid-format', { cause });
+        }
+        const count = rhwpDocument.pageCount();
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new HwpViewerError('corrupted', 'diag.hwp.corrupted');
+        let renderedCount = Math.min(count, HWP_MAX_RENDERED_PAGES);
+        meta.textContent += ` · ${ctx.i18n.t('hwp.pages', { count })}`;
+        try {
+            renderPageRange(rhwpDocument, 0, renderedCount, content, ctx, options.signal);
+        }
+        finally {
+            freeDocument();
+        }
+        loading.remove();
+        if (count > renderedCount) {
+            const status = el('div', 'omni-hwp__status');
+            const progress = el('span', undefined, ctx.i18n.t('diag.hwp.page-limit', { rendered: renderedCount, total: count }));
+            const more = el('button', 'omni-hwp__load-more', ctx.i18n.t('hwp.loadMorePages'));
+            more.type = 'button';
+            status.append(progress, more);
+            content.append(status);
+            listen(more, 'click', (async () => {
+                if (cleaned || !loadedRhwp)
+                    return;
+                more.disabled = true;
+                let batchDocument;
+                const batchStart = renderedCount;
+                try {
+                    batchDocument = new loadedRhwp.HwpDocument(input.data);
+                    const next = Math.min(count, batchStart + HWP_MAX_RENDERED_PAGES);
+                    renderPageRange(batchDocument, batchStart, next, content, ctx, options.signal, status);
+                    renderedCount = next;
+                    if (renderedCount >= count)
+                        status.remove();
+                    else {
+                        progress.textContent = ctx.i18n.t('diag.hwp.page-limit', { rendered: renderedCount, total: count });
+                        more.disabled = false;
+                    }
+                }
+                catch (error) {
+                    for (const page of [...content.querySelectorAll('.omni-hwp__page')])
+                        if (Number(page.getAttribute('data-page-index')) >= batchStart)
+                            page.remove();
+                    progress.textContent = ctx.i18n.t('diag.hwp.corrupted');
+                    more.disabled = false;
+                    ctx.logger.log('error', `hwp: additional page render failed: ${String(error)}`);
+                }
+                finally {
+                    batchDocument?.free?.();
+                }
+            }));
+        }
+        if (count === 0)
+            content.append(el('div', 'omni-hwp__status', ctx.i18n.t('hwp.empty')));
+    }
+    catch (error) {
+        cleanup();
+        if (error instanceof MountAbortedError || error instanceof HwpViewerError)
+            throw error;
+        ctx.logger.log('error', `hwp: renderer failed: ${String(error)}`);
+        throw new HwpViewerError(deps.loadRhwp ? 'corrupted' : 'missing-dependency', deps.loadRhwp ? 'diag.hwp.corrupted' : 'diag.hwp.missing-dependency', { cause: error });
+    }
+    return { controller, dispose: cleanup };
+}
+function renderPageRange(documentHandle, start, end, content, ctx, signal, before) {
+    for (let pageIndex = start; pageIndex < end; pageIndex++) {
+        if (signal?.aborted)
+            throw new MountAbortedError();
+        const page = el('section', 'omni-hwp__page');
+        page.dataset.pageIndex = String(pageIndex);
+        page.setAttribute('aria-label', ctx.i18n.t('hwp.pageLabel', { page: pageIndex + 1 }));
+        page.append(svgElement(documentHandle.renderPageSvg(pageIndex)));
+        if (before)
+            content.insertBefore(page, before);
+        else
+            content.append(page);
+    }
+}
+function formatBytes(bytes) { if (bytes < 1024)
+    return `${bytes} B`; if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)} KB`; return `${(bytes / 1024 / 1024).toFixed(1)} MB`; }

package/dist/viewers/hwp/self-loading.d.ts

@@ -0,0 +1,2 @@
+import type { HwpViewerDeps } from './index.js';
+export declare function loadHwpViewerDeps(): Promise<HwpViewerDeps>;

package/dist/viewers/hwp/self-loading.js

@@ -0,0 +1,6 @@
+export async function loadHwpViewerDeps() {
+    const imported = await import('@rhwp/core');
+    if (typeof imported.default === 'function')
+        await imported.default();
+    return { loadRhwp: async () => imported };
+}

package/dist/viewers/hwp/styles.d.ts

@@ -0,0 +1 @@
+export declare const hwpViewerCss = "\n:host{display:block;height:100%;color:var(--omni-fg,#d4d4d4);background:var(--omni-bg,#1e1e1e)}\n.omni-hwp{display:flex;flex-direction:column;height:100%;font:13px system-ui,-apple-system,\"Segoe UI\",\"Noto Sans KR\",sans-serif}\n.omni-hwp__header,.omni-hwp__toolbar{display:flex;align-items:center;gap:12px;padding:10px 16px;background:var(--omni-panel-bg,#252526);border-bottom:1px solid var(--omni-border,#3c3c3c)}\n.omni-hwp__header{justify-content:space-between}.omni-hwp__title{overflow:hidden;font-weight:600;text-overflow:ellipsis;white-space:nowrap}.omni-hwp__meta{opacity:.7;font-size:12px;white-space:nowrap}\n.omni-hwp__toolbar{justify-content:center}.omni-hwp__toolbar button{min-width:34px;padding:6px 10px;color:inherit;background:var(--omni-control-bg,#3a3d41);border:1px solid var(--omni-border,#555);border-radius:6px;cursor:pointer}.omni-hwp__zoom{min-width:52px;text-align:center;opacity:.8}\n.omni-hwp__viewport{position:relative;flex:1;overflow:auto;padding:28px 24px 48px;background:radial-gradient(circle at top,#ffffff0d,transparent 28%)}\n.omni-hwp__content{display:grid;width:max-content;min-width:100%;gap:24px;justify-items:center;transform-origin:top center}\n.omni-hwp__page{display:block;overflow:hidden;background:#fff;border-radius:4px;box-shadow:0 18px 40px #00000047}.omni-hwp__page svg{display:block;max-width:100%;height:auto}\n.omni-hwp__status,.omni-hwp__error{margin:auto;padding:24px;text-align:center}.omni-hwp__error{color:var(--omni-danger,#f48771)}\n.omni-hwp__status{display:flex;align-items:center;gap:12px}.omni-hwp__load-more{padding:7px 12px;color:inherit;background:var(--omni-control-bg,#3a3d41);border:1px solid var(--omni-border,#555);border-radius:6px;cursor:pointer}.omni-hwp__load-more:disabled{opacity:.5}\n@media print{.omni-hwp__header,.omni-hwp__toolbar{display:none}.omni-hwp__viewport{overflow:visible;padding:0}.omni-hwp__content{display:block;transform:none!important}.omni-hwp__page{box-shadow:none;break-after:page}}\n";

package/dist/viewers/hwp/styles.js

@@ -0,0 +1,13 @@
+export const hwpViewerCss = `
+:host{display:block;height:100%;color:var(--omni-fg,#d4d4d4);background:var(--omni-bg,#1e1e1e)}
+.omni-hwp{display:flex;flex-direction:column;height:100%;font:13px system-ui,-apple-system,"Segoe UI","Noto Sans KR",sans-serif}
+.omni-hwp__header,.omni-hwp__toolbar{display:flex;align-items:center;gap:12px;padding:10px 16px;background:var(--omni-panel-bg,#252526);border-bottom:1px solid var(--omni-border,#3c3c3c)}
+.omni-hwp__header{justify-content:space-between}.omni-hwp__title{overflow:hidden;font-weight:600;text-overflow:ellipsis;white-space:nowrap}.omni-hwp__meta{opacity:.7;font-size:12px;white-space:nowrap}
+.omni-hwp__toolbar{justify-content:center}.omni-hwp__toolbar button{min-width:34px;padding:6px 10px;color:inherit;background:var(--omni-control-bg,#3a3d41);border:1px solid var(--omni-border,#555);border-radius:6px;cursor:pointer}.omni-hwp__zoom{min-width:52px;text-align:center;opacity:.8}
+.omni-hwp__viewport{position:relative;flex:1;overflow:auto;padding:28px 24px 48px;background:radial-gradient(circle at top,#ffffff0d,transparent 28%)}
+.omni-hwp__content{display:grid;width:max-content;min-width:100%;gap:24px;justify-items:center;transform-origin:top center}
+.omni-hwp__page{display:block;overflow:hidden;background:#fff;border-radius:4px;box-shadow:0 18px 40px #00000047}.omni-hwp__page svg{display:block;max-width:100%;height:auto}
+.omni-hwp__status,.omni-hwp__error{margin:auto;padding:24px;text-align:center}.omni-hwp__error{color:var(--omni-danger,#f48771)}
+.omni-hwp__status{display:flex;align-items:center;gap:12px}.omni-hwp__load-more{padding:7px 12px;color:inherit;background:var(--omni-control-bg,#3a3d41);border:1px solid var(--omni-border,#555);border-radius:6px;cursor:pointer}.omni-hwp__load-more:disabled{opacity:.5}
+@media print{.omni-hwp__header,.omni-hwp__toolbar{display:none}.omni-hwp__viewport{overflow:visible;padding:0}.omni-hwp__content{display:block;transform:none!important}.omni-hwp__page{box-shadow:none;break-after:page}}
+`;

package/dist/viewers/image/controller.d.ts

@@ -0,0 +1,210 @@
+import type { Diagnostic, ParseFailure } from '../../parsers/types.js';
+/** Zoom range and step (image.md §3): 10 %–500 %, 25 % increments. */
+export declare const MIN_ZOOM = 0.1;
+export declare const MAX_ZOOM = 5;
+export declare const ZOOM_STEP = 0.25;
+/** Undo history depth cap (image.md §4 maxUndoEntries). */
+export declare const MAX_UNDO_ENTRIES = 100;
+export type Rotation = 0 | 90 | 180 | 270;
+export type AnnotationTool = 'select' | 'brush' | 'eraser' | 'line' | 'rectangle' | 'circle' | 'text';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface AnnotationStyle {
+    color: string;
+    fillOpacity: number;
+    borderOpacity: number;
+    fontSize: number;
+    brushSize: number;
+}
+export declare const DEFAULT_STYLE: AnnotationStyle;
+/** Annotation geometry, all in source pixel coordinates. */
+export type Annotation = {
+    id: string;
+    type: 'rectangle';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    style: AnnotationStyle;
+} | {
+    id: string;
+    type: 'circle';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    style: AnnotationStyle;
+} | {
+    id: string;
+    type: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    style: AnnotationStyle;
+} | {
+    id: string;
+    type: 'text';
+    x: number;
+    y: number;
+    text: string;
+    style: AnnotationStyle;
+} | {
+    id: string;
+    type: 'stroke';
+    points: Point[];
+    erase: boolean;
+    style: AnnotationStyle;
+};
+export interface FilterState {
+    /** Percent values (image.md §3). brightness/contrast/saturation 0–200, grayscale 0–100. */
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    grayscale: number;
+}
+export declare const NEUTRAL_FILTER: FilterState;
+export type FilterPreset = 'original' | 'bright' | 'dark' | 'vintage' | 'bw';
+/**
+ * Preset filter values. NOTE (image.md §3, I-preset): the exact numbers must be
+ * pinned to the existing VS Code / Obsidian fixtures during migration — these
+ * are the working defaults until those goldens land.
+ */
+export declare const FILTER_PRESETS: Record<FilterPreset, FilterState>;
+export type GridMode = 'cell-size' | 'rows-cols';
+export interface GridState {
+    visible: boolean;
+    /** Preserves both VS Code/Obsidian (source-pixel cell) and Web (rows×cols)
+     *  meanings without lossy conversion on platform switch (image.md I3). */
+    mode: GridMode;
+    cellWidth: number;
+    cellHeight: number;
+    rows: number;
+    cols: number;
+}
+export declare const DEFAULT_GRID: GridState;
+/** Image metadata surfaced after decode (mount fills this via `setDocument`). */
+export interface ImageMeta {
+    mime: string;
+    width: number;
+    height: number;
+    byteLength: number;
+    animated: boolean;
+}
+export interface ImageViewState {
+    status: 'ok' | 'partial' | 'failed';
+    failure: ParseFailure | null;
+    diagnostics: Diagnostic[];
+    meta: ImageMeta | null;
+    /** Editing/PNG export disabled (canvas limit exceeded → partial, image.md §4). */
+    editingEnabled: boolean;
+    zoom: number;
+    fitMode: boolean;
+    rotation: Rotation;
+    flipH: boolean;
+    flipV: boolean;
+    filter: FilterState;
+    preset: FilterPreset | null;
+    grid: GridState;
+    annotations: Annotation[];
+    tool: AnnotationTool;
+    selectedId: string | null;
+    style: AnnotationStyle;
+    dirty: boolean;
+    canUndo: boolean;
+}
+export type ImageAction = {
+    type: 'set-zoom';
+    zoom: number;
+} | {
+    type: 'zoom-in';
+} | {
+    type: 'zoom-out';
+} | {
+    type: 'fit';
+} | {
+    type: 'actual-size';
+} | {
+    type: 'rotate-cw';
+} | {
+    type: 'flip-h';
+} | {
+    type: 'flip-v';
+} | {
+    type: 'reset';
+} | {
+    type: 'set-filter';
+    filter: Partial<FilterState>;
+} | {
+    type: 'set-preset';
+    preset: FilterPreset;
+} | {
+    type: 'toggle-grid';
+} | {
+    type: 'set-grid-mode';
+    mode: GridMode;
+} | {
+    type: 'set-grid-value';
+    key: 'cellWidth' | 'cellHeight' | 'rows' | 'cols';
+    value: number;
+} | {
+    type: 'set-tool';
+    tool: AnnotationTool;
+} | {
+    type: 'set-style';
+    style: Partial<AnnotationStyle>;
+} | {
+    type: 'add-annotation';
+    annotation: Annotation;
+} | {
+    type: 'select-annotation';
+    id: string | null;
+} | {
+    type: 'move-annotation';
+    dx: number;
+    dy: number;
+} | {
+    type: 'update-annotation';
+    id: string;
+    patch: Partial<Extract<Annotation, {
+        type: 'text';
+    }>>;
+} | {
+    type: 'delete-annotation';
+    id?: string;
+} | {
+    type: 'undo';
+};
+export interface ImageController {
+    readonly state: ImageViewState;
+    dispatch(action: ImageAction): void;
+    subscribe(listener: (state: ImageViewState) => void): () => void;
+    /** CSS `filter` string for the current filter values (display + export). */
+    filterCss(): string;
+    /** Record decode metadata / status; editingEnabled gates the canvas ops. */
+    setDocument(input: {
+        status: 'ok' | 'partial' | 'failed';
+        failure?: ParseFailure | null;
+        diagnostics?: Diagnostic[];
+        meta?: ImageMeta | null;
+        editingEnabled?: boolean;
+    }): void;
+}
+/** Snap zoom to the 25 % grid within range (image.md §3). */
+export declare function normalizeZoom(zoom: number): number;
+export declare function filterToCss(filter: FilterState): string;
+export declare function createImageController(): ImageController;
+/** Factory helper for the renderer: build an annotation with a fresh id. */
+export declare function makeAnnotation(spec: Omit<Extract<Annotation, {
+    type: 'rectangle';
+}>, 'id'> | Omit<Extract<Annotation, {
+    type: 'circle';
+}>, 'id'> | Omit<Extract<Annotation, {
+    type: 'line';
+}>, 'id'> | Omit<Extract<Annotation, {
+    type: 'text';
+}>, 'id'> | Omit<Extract<Annotation, {
+    type: 'stroke';
+}>, 'id'>): Annotation;