omni-viewer-core 0.1.0

package/dist/viewers/image/controller.js

@@ -0,0 +1,336 @@
+// ImageController — the behavior-controller layer for the image viewer
+// (DESIGN.md §3-②, docs/viewers/image.md §2 편집 모델). Pure state machine:
+// no DOM, no host services, no ImageBitmap. The DOM renderer (mount.ts) and a
+// future web (Vue) host consume the same controller so interaction semantics
+// and the conformance kit's "action sequence → normalized state" stay shared.
+//
+// Coordinates: every annotation is stored in *source pixel* coordinates. View
+// transform (zoom/fit) is display-only and never mutates annotation geometry;
+// rotation/flip/filter are edits that the exporter composes into the output
+// (image.md §2, §5 export 기준선).
+/** Zoom range and step (image.md §3): 10 %–500 %, 25 % increments. */
+export const MIN_ZOOM = 0.1;
+export const MAX_ZOOM = 5;
+export const ZOOM_STEP = 0.25;
+/** Undo history depth cap (image.md §4 maxUndoEntries). */
+export const MAX_UNDO_ENTRIES = 100;
+export const DEFAULT_STYLE = {
+    color: '#e23b3b',
+    fillOpacity: 0,
+    borderOpacity: 1,
+    fontSize: 16,
+    brushSize: 4
+};
+export const NEUTRAL_FILTER = {
+    brightness: 100,
+    contrast: 100,
+    saturation: 100,
+    grayscale: 0
+};
+/**
+ * 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 const FILTER_PRESETS = {
+    original: { brightness: 100, contrast: 100, saturation: 100, grayscale: 0 },
+    bright: { brightness: 120, contrast: 105, saturation: 105, grayscale: 0 },
+    dark: { brightness: 80, contrast: 110, saturation: 100, grayscale: 0 },
+    vintage: { brightness: 110, contrast: 90, saturation: 80, grayscale: 20 },
+    bw: { brightness: 100, contrast: 100, saturation: 0, grayscale: 100 }
+};
+export const DEFAULT_GRID = {
+    visible: false,
+    mode: 'cell-size',
+    cellWidth: 32,
+    cellHeight: 32,
+    rows: 4,
+    cols: 4
+};
+let idCounter = 0;
+/** Deterministic monotonic ids so conformance snapshots stay comparable. */
+function nextId() {
+    return `a${idCounter++}`;
+}
+function clamp(value, lo, hi) {
+    return Math.min(hi, Math.max(lo, value));
+}
+/** Snap zoom to the 25 % grid within range (image.md §3). */
+export function normalizeZoom(zoom) {
+    const snapped = Math.round(zoom / ZOOM_STEP) * ZOOM_STEP;
+    return clamp(Number(snapped.toFixed(4)), MIN_ZOOM, MAX_ZOOM);
+}
+export function filterToCss(filter) {
+    return (`brightness(${filter.brightness}%) contrast(${filter.contrast}%) ` +
+        `saturate(${filter.saturation}%) grayscale(${filter.grayscale}%)`);
+}
+function initialEdit() {
+    return {
+        rotation: 0,
+        flipH: false,
+        flipV: false,
+        filter: { ...NEUTRAL_FILTER },
+        preset: 'original',
+        grid: { ...DEFAULT_GRID },
+        annotations: []
+    };
+}
+function cloneEdit(edit) {
+    return {
+        rotation: edit.rotation,
+        flipH: edit.flipH,
+        flipV: edit.flipV,
+        filter: { ...edit.filter },
+        preset: edit.preset,
+        grid: { ...edit.grid },
+        annotations: edit.annotations.map(cloneAnnotation)
+    };
+}
+function cloneAnnotation(a) {
+    if (a.type === 'stroke') {
+        return { ...a, points: a.points.map((p) => ({ ...p })), style: { ...a.style } };
+    }
+    return { ...a, style: { ...a.style } };
+}
+export function createImageController() {
+    const listeners = new Set();
+    let status = 'ok';
+    let failure = null;
+    let diagnostics = [];
+    let meta = null;
+    let editingEnabled = true;
+    let zoom = 1;
+    let fitMode = true;
+    let edit = initialEdit();
+    let tool = 'select';
+    let selectedId = null;
+    let style = { ...DEFAULT_STYLE };
+    // Cursor-based linear history (image.md I4): undo only in v1, but the model
+    // supports a future redo without a refactor. history[0] is the initial edit.
+    const history = [cloneEdit(edit)];
+    let historyIndex = 0;
+    function emit() {
+        const snapshot = buildState();
+        for (const listener of listeners)
+            listener(snapshot);
+    }
+    function buildState() {
+        return {
+            status,
+            failure,
+            diagnostics,
+            meta,
+            editingEnabled,
+            zoom,
+            fitMode,
+            rotation: edit.rotation,
+            flipH: edit.flipH,
+            flipV: edit.flipV,
+            filter: { ...edit.filter },
+            preset: edit.preset,
+            grid: { ...edit.grid },
+            annotations: edit.annotations.map(cloneAnnotation),
+            tool,
+            selectedId,
+            style: { ...style },
+            dirty: historyIndex !== 0,
+            canUndo: historyIndex > 0
+        };
+    }
+    /** Commit the current `edit` as a new history entry (image.md §4: drop the
+     *  oldest past the cap; a new edit truncates any undone tail). */
+    function pushHistory() {
+        history.splice(historyIndex + 1); // drop redo branch (none in v1 UI)
+        history.push(cloneEdit(edit));
+        historyIndex = history.length - 1;
+        while (history.length > MAX_UNDO_ENTRIES + 1) {
+            history.shift();
+            historyIndex--;
+        }
+    }
+    function restore(index) {
+        historyIndex = index;
+        edit = cloneEdit(history[index]);
+        // A restored document may no longer contain the selected annotation.
+        if (selectedId && !edit.annotations.some((a) => a.id === selectedId)) {
+            selectedId = null;
+        }
+    }
+    /** Grid inputs keep the previous valid value on 0/negative/NaN (image.md §3). */
+    function normalizeGridValue(value) {
+        if (!Number.isFinite(value) || value <= 0)
+            return null;
+        return Math.floor(value);
+    }
+    function dispatch(action) {
+        switch (action.type) {
+            // ---- view (display-only) ----------------------------------------
+            case 'set-zoom':
+                zoom = normalizeZoom(action.zoom);
+                fitMode = false;
+                break;
+            case 'zoom-in':
+                zoom = normalizeZoom(zoom + ZOOM_STEP);
+                fitMode = false;
+                break;
+            case 'zoom-out':
+                zoom = normalizeZoom(zoom - ZOOM_STEP);
+                fitMode = false;
+                break;
+            case 'fit':
+                fitMode = true;
+                break;
+            case 'actual-size':
+                zoom = 1;
+                fitMode = false;
+                break;
+            // ---- edits (undoable) -------------------------------------------
+            case 'rotate-cw':
+                edit.rotation = ((edit.rotation + 90) % 360);
+                pushHistory();
+                break;
+            case 'flip-h':
+                edit.flipH = !edit.flipH;
+                pushHistory();
+                break;
+            case 'flip-v':
+                edit.flipV = !edit.flipV;
+                pushHistory();
+                break;
+            case 'reset':
+                // Transform, filter, grid, annotation and selection all return to
+                // initial (image.md §3). Zoom/fit reset too (display-only).
+                edit = initialEdit();
+                zoom = 1;
+                fitMode = true;
+                selectedId = null;
+                pushHistory();
+                break;
+            case 'set-filter':
+                edit.filter = {
+                    brightness: clamp(action.filter.brightness ?? edit.filter.brightness, 0, 200),
+                    contrast: clamp(action.filter.contrast ?? edit.filter.contrast, 0, 200),
+                    saturation: clamp(action.filter.saturation ?? edit.filter.saturation, 0, 200),
+                    grayscale: clamp(action.filter.grayscale ?? edit.filter.grayscale, 0, 100)
+                };
+                edit.preset = null;
+                pushHistory();
+                break;
+            case 'set-preset':
+                edit.filter = { ...FILTER_PRESETS[action.preset] };
+                edit.preset = action.preset;
+                pushHistory();
+                break;
+            case 'toggle-grid':
+                edit.grid = { ...edit.grid, visible: !edit.grid.visible };
+                pushHistory();
+                break;
+            case 'set-grid-mode':
+                edit.grid = { ...edit.grid, mode: action.mode };
+                pushHistory();
+                break;
+            case 'set-grid-value': {
+                const normalized = normalizeGridValue(action.value);
+                if (normalized === null)
+                    return; // keep previous valid value; no history
+                edit.grid = { ...edit.grid, [action.key]: normalized };
+                pushHistory();
+                break;
+            }
+            // ---- annotations -------------------------------------------------
+            case 'set-tool':
+                tool = action.tool;
+                break;
+            case 'set-style':
+                style = { ...style, ...action.style };
+                if (selectedId) {
+                    const target = edit.annotations.find((a) => a.id === selectedId);
+                    if (target) {
+                        target.style = { ...target.style, ...action.style };
+                        pushHistory();
+                    }
+                }
+                break;
+            case 'add-annotation':
+                edit.annotations = [...edit.annotations, cloneAnnotation(action.annotation)];
+                selectedId = action.annotation.id;
+                pushHistory();
+                break;
+            case 'select-annotation':
+                selectedId = action.id;
+                break; // selection is not an edit
+            case 'move-annotation': {
+                if (!selectedId)
+                    return;
+                const target = edit.annotations.find((a) => a.id === selectedId);
+                if (!target)
+                    return;
+                edit.annotations = edit.annotations.map((a) => a.id === selectedId ? translate(a, action.dx, action.dy) : a);
+                pushHistory();
+                break;
+            }
+            case 'update-annotation': {
+                const target = edit.annotations.find((a) => a.id === action.id);
+                if (!target || target.type !== 'text')
+                    return;
+                edit.annotations = edit.annotations.map((a) => a.id === action.id && a.type === 'text' ? { ...a, ...action.patch } : a);
+                pushHistory();
+                break;
+            }
+            case 'delete-annotation': {
+                const id = action.id ?? selectedId;
+                if (!id || !edit.annotations.some((a) => a.id === id))
+                    return;
+                edit.annotations = edit.annotations.filter((a) => a.id !== id);
+                if (selectedId === id)
+                    selectedId = null;
+                pushHistory();
+                break;
+            }
+            // ---- history -----------------------------------------------------
+            case 'undo':
+                if (historyIndex === 0)
+                    return;
+                restore(historyIndex - 1);
+                break;
+        }
+        emit();
+    }
+    function setDocument(input) {
+        status = input.status;
+        failure = input.failure ?? null;
+        diagnostics = input.diagnostics ?? [];
+        meta = input.meta ?? null;
+        editingEnabled = input.editingEnabled ?? input.status !== 'failed';
+        emit();
+    }
+    return {
+        get state() {
+            return buildState();
+        },
+        dispatch,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        filterCss() {
+            return filterToCss(edit.filter);
+        },
+        setDocument
+    };
+}
+/** Shift every coordinate of an annotation by (dx, dy) in source pixels. */
+function translate(a, dx, dy) {
+    switch (a.type) {
+        case 'line':
+            return { ...a, x1: a.x1 + dx, y1: a.y1 + dy, x2: a.x2 + dx, y2: a.y2 + dy };
+        case 'stroke':
+            return { ...a, points: a.points.map((p) => ({ x: p.x + dx, y: p.y + dy })) };
+        default:
+            return { ...a, x: a.x + dx, y: a.y + dy };
+    }
+}
+/** Factory helper for the renderer: build an annotation with a fresh id. */
+export function makeAnnotation(spec) {
+    return { id: nextId(), ...spec };
+}

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

@@ -0,0 +1,54 @@
+import type { ParseResult } from '../../parsers/types.js';
+import type { ImageMeta } from './controller.js';
+export type ImageMime = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp' | 'image/webp' | 'image/svg+xml';
+/** A decoded document is just metadata — the drawable lives separately so the
+ *  controller stays DOM-free (image.md §2). */
+export interface ImageDocument extends ImageMeta {
+}
+export type ImageLoadResult = ParseResult<ImageDocument>;
+/**
+ * Byte-level MIME sniff (image.md §1). Returns null when the bytes match no
+ * known raster signature and the content is not SVG text — the caller then
+ * declines the image viewer (extension/byte conflict → fallback).
+ */
+export declare function detectImageMime(data: Uint8Array, fileName: string): ImageMime | null;
+/**
+ * SVG text probe (image.md §1): scan the first ~1 KiB for an `<svg` root while
+ * rejecting `<html` (a document, not an image). BOM / XML declaration /
+ * comments before the root are tolerated.
+ */
+export declare function isSvgText(data: Uint8Array): boolean;
+/** Cheap animation sniff for the first-frame policy (image.md I2). Conservative:
+ *  a false negative just means we show a static frame without the badge. */
+export declare function isAnimated(data: Uint8Array, mime: ImageMime): boolean;
+/**
+ * Enforce the input-byte cap before touching a decoder (image.md §4). Returns a
+ * `failed(limit-exceeded)` result, or null when within budget.
+ */
+export declare function checkInputLimit(data: Uint8Array, maxInputBytes?: number): ImageLoadResult | null;
+/** A decoded image plus its disposable browser resources (mount owns cleanup). */
+export interface DecodedImage {
+    load: ImageLoadResult;
+    /** Drawable for canvas composition; absent on failure. */
+    source?: CanvasImageSource & {
+        width: number;
+        height: number;
+    };
+    /** Revoked on dispose. */
+    objectUrl?: string;
+    dispose(): void;
+}
+/**
+ * Decode input bytes into a drawable + normalized ImageLoadResult. Never throws
+ * on input-caused failure (parser determinism rule): unsupported/corrupt →
+ * `invalid-format`/`corrupted`, oversize → `limit-exceeded`, no decoder →
+ * `missing-dependency`. Honors `signal` and cleans up on abort.
+ */
+export declare function decodeImage(input: {
+    fileName: string;
+    data: Uint8Array;
+}, options?: {
+    signal?: AbortSignal;
+    maxInputBytes?: number;
+    maxDecodedPixels?: number;
+}): Promise<DecodedImage>;

package/dist/viewers/image/decode.js

@@ -0,0 +1,150 @@
+// Image decoding + detection (docs/viewers/image.md §1, §2, §4). The pure
+// helpers (MIME sniffing, SVG probing, animation + limit checks) are engine-
+// independent and unit-tested; the async `decodeImage` uses browser decoders
+// (createImageBitmap / <img> + blob URL) and is exercised by the mount smoke.
+//
+// SVG isolation (image.md I1, §5 보안): SVG is decoded only through an
+// `image/svg+xml` blob URL into <img>/createImageBitmap — never injected into
+// the document DOM. img-loaded SVG neither runs scripts nor fetches external
+// resources, so the decode path itself is the isolation boundary.
+import { IMAGE_LIMITS } from './limits.js';
+const startsWith = (data, sig, offset = 0) => data.length >= offset + sig.length && sig.every((b, i) => data[offset + i] === b);
+/**
+ * Byte-level MIME sniff (image.md §1). Returns null when the bytes match no
+ * known raster signature and the content is not SVG text — the caller then
+ * declines the image viewer (extension/byte conflict → fallback).
+ */
+export function detectImageMime(data, fileName) {
+    if (startsWith(data, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return 'image/png';
+    if (startsWith(data, [0xff, 0xd8, 0xff]))
+        return 'image/jpeg';
+    if (startsWith(data, [0x47, 0x49, 0x46, 0x38]))
+        return 'image/gif';
+    if (startsWith(data, [0x42, 0x4d]))
+        return 'image/bmp';
+    if (startsWith(data, [0x52, 0x49, 0x46, 0x46]) && startsWith(data, [0x57, 0x45, 0x42, 0x50], 8))
+        return 'image/webp';
+    if (isSvgText(data) && /\.svg$/i.test(fileName))
+        return 'image/svg+xml';
+    return null;
+}
+/**
+ * SVG text probe (image.md §1): scan the first ~1 KiB for an `<svg` root while
+ * rejecting `<html` (a document, not an image). BOM / XML declaration /
+ * comments before the root are tolerated.
+ */
+export function isSvgText(data) {
+    const head = new TextDecoder('utf-8', { fatal: false })
+        .decode(data.subarray(0, 1024))
+        .toLowerCase();
+    if (head.includes('<html'))
+        return false;
+    return head.includes('<svg');
+}
+/** Cheap animation sniff for the first-frame policy (image.md I2). Conservative:
+ *  a false negative just means we show a static frame without the badge. */
+export function isAnimated(data, mime) {
+    if (mime === 'image/gif') {
+        // More than one Graphic Control Extension (0x21 0xF9) ⇒ multiple frames.
+        let count = 0;
+        for (let i = 0; i + 1 < data.length; i++) {
+            if (data[i] === 0x21 && data[i + 1] === 0xf9 && ++count > 1)
+                return true;
+        }
+        return false;
+    }
+    if (mime === 'image/webp') {
+        // 'ANIM' chunk marks an animated WebP.
+        for (let i = 12; i + 3 < data.length && i < 4096; i++) {
+            if (data[i] === 0x41 && data[i + 1] === 0x4e && data[i + 2] === 0x49 && data[i + 3] === 0x4d)
+                return true;
+        }
+    }
+    return false;
+}
+function fail(code, messageKey, args) {
+    return {
+        status: 'failed',
+        failure: { code, retryable: false, messageKey, ...(args ? { args } : {}) },
+        diagnostics: []
+    };
+}
+/**
+ * Enforce the input-byte cap before touching a decoder (image.md §4). Returns a
+ * `failed(limit-exceeded)` result, or null when within budget.
+ */
+export function checkInputLimit(data, maxInputBytes = IMAGE_LIMITS.maxInputBytes) {
+    if (data.byteLength > maxInputBytes) {
+        return fail('limit-exceeded', 'diag.limit-exceeded.input', { maxBytes: maxInputBytes });
+    }
+    return null;
+}
+/**
+ * Decode input bytes into a drawable + normalized ImageLoadResult. Never throws
+ * on input-caused failure (parser determinism rule): unsupported/corrupt →
+ * `invalid-format`/`corrupted`, oversize → `limit-exceeded`, no decoder →
+ * `missing-dependency`. Honors `signal` and cleans up on abort.
+ */
+export async function decodeImage(input, options = {}) {
+    const noop = { load: fail('invalid-format', 'diag.image.invalid-format'), dispose() { } };
+    const limitHit = checkInputLimit(input.data, options.maxInputBytes);
+    if (limitHit)
+        return { load: limitHit, dispose() { } };
+    const mime = detectImageMime(input.data, input.fileName);
+    if (!mime)
+        return noop;
+    if (typeof createImageBitmap !== 'function' || typeof Blob !== 'function') {
+        return { load: fail('missing-dependency', 'diag.image.invalid-format'), dispose() { } };
+    }
+    const blob = new Blob([input.data.slice().buffer], { type: mime });
+    let objectUrl;
+    let bitmap;
+    const dispose = () => {
+        bitmap?.close?.();
+        if (objectUrl && typeof URL !== 'undefined')
+            URL.revokeObjectURL(objectUrl);
+    };
+    try {
+        // SVG and raster both go through blob decoding — SVG via <img> keeps it
+        // isolated (no DOM injection, no script execution).
+        bitmap = await createImageBitmap(blob);
+        if (options.signal?.aborted) {
+            dispose();
+            return { load: fail('aborted', 'diag.aborted'), dispose() { } };
+        }
+        const pixels = bitmap.width * bitmap.height;
+        const maxPixels = options.maxDecodedPixels ?? IMAGE_LIMITS.maxDecodedPixels;
+        if (pixels > maxPixels) {
+            // v1: no downscaler wired yet — decline rather than risk OOM (I6).
+            dispose();
+            return { load: fail('limit-exceeded', 'diag.image.limit-exceeded.pixels'), dispose() { } };
+        }
+        const animated = isAnimated(input.data, mime);
+        const diagnostics = [];
+        if (animated) {
+            diagnostics.push({
+                severity: 'info',
+                code: 'animated-first-frame',
+                messageKey: 'diag.image.animated-first-frame'
+            });
+        }
+        const doc = {
+            mime,
+            width: bitmap.width,
+            height: bitmap.height,
+            byteLength: input.data.byteLength,
+            animated
+        };
+        return {
+            load: { status: animated ? 'partial' : 'ok', document: doc, diagnostics },
+            source: bitmap,
+            ...(objectUrl ? { objectUrl } : {}),
+            dispose
+        };
+    }
+    catch {
+        dispose();
+        return { load: fail('corrupted', 'diag.image.corrupted'), dispose() { } };
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { FileSaveService, FileWritebackService, HostContext, ImageBackgroundRemovalService, ImageSpriteDetectionService } from '../../host/index.js';
+import { type MountOptions, type ViewerHandle, type ViewerInput } from '../types.js';
+export { createImageController } from './controller.js';
+export type { ImageController, ImageViewState, ImageAction, Annotation } from './controller.js';
+export { decodeImage, detectImageMime, isSvgText, isAnimated } from './decode.js';
+export type { ImageLoadResult, ImageDocument, ImageMime } from './decode.js';
+export { IMAGE_LIMITS, canvasEditable } from './limits.js';
+export { imageViewerCss } from './styles.js';
+/** Viewer metadata — single source for the registry codegen (DESIGN.md §7). */
+export declare const IMAGE_VIEWER_META: {
+    id: string;
+    displayNameKey: string;
+    extensions: string[];
+    priority: number;
+    requiredServices: readonly [];
+    optionalServices: readonly ["save", "writeback", "backgroundRemoval", "spriteDetection"];
+    inputOwnership: "borrows";
+};
+export type ImageViewerContext = HostContext & {
+    save?: FileSaveService;
+    writeback?: FileWritebackService;
+    backgroundRemoval?: ImageBackgroundRemovalService;
+    spriteDetection?: ImageSpriteDetectionService;
+};
+export interface ImageViewerHandle extends ViewerHandle {
+    isDirty(): boolean;
+}
+export interface ImageMountOptions extends MountOptions {
+    maxInputBytes?: number;
+    maxDecodedPixels?: number;
+}
+/**
+ * Export file name (image.md I7): the edited image always saves as PNG, so the
+ * proposed name is coerced to `.png` regardless of the source extension. This
+ * is an intentional compatibility change — the UI announces it.
+ */
+export declare function imageExportFileName(sourceName: string): string;
+export declare function mountImageViewer(input: ViewerInput, container: HTMLElement, ctx: ImageViewerContext, options?: ImageMountOptions): Promise<ImageViewerHandle>;