fundus 0.0.2 → 0.0.4

package/dist/core/reference-graph.js

@@ -0,0 +1,138 @@
+/**
+ * Ask each asset's owning plugin for the references in its parameters. Assets
+ * whose type is unknown or whose parameters do not validate contribute no
+ * references — those problems are reported by the regular validation pass.
+ */
+export function collectAllReferences(library, plugins) {
+    const referencesByAsset = {};
+    for (const [assetId, record] of Object.entries(library.assets)) {
+        referencesByAsset[assetId] = [];
+        const plugin = plugins[record.type];
+        if (!plugin?.collectReferences)
+            continue;
+        try {
+            referencesByAsset[assetId] = plugin.collectReferences(plugin.validateParameters(record.parameters));
+        }
+        catch {
+            // Invalid parameters — reported as a validation issue elsewhere.
+        }
+    }
+    return referencesByAsset;
+}
+/**
+ * Reference *errors* (they block build/codegen): a reference to an unknown
+ * asset, a target whose type is not among the field's expected types, and
+ * cycles (composition is acyclic by nature).
+ */
+export function referenceErrors(library, referencesByAsset) {
+    const issues = [];
+    for (const [assetId, references] of Object.entries(referencesByAsset)) {
+        for (const reference of references) {
+            if (!Object.hasOwn(library.assets, reference.assetId)) {
+                issues.push({
+                    assetId,
+                    message: `Reference "${reference.field}" points at unknown asset "${reference.assetId}".`
+                });
+                continue;
+            }
+            const targetType = library.assets[reference.assetId].type;
+            if (reference.expectedTypes.length > 0 && !reference.expectedTypes.includes(targetType)) {
+                issues.push({
+                    assetId,
+                    message: `Reference "${reference.field}" points at "${reference.assetId}" of type ` +
+                        `"${targetType}" — expected ${reference.expectedTypes.map((type) => `"${type}"`).join(' or ')}.`
+                });
+            }
+        }
+    }
+    issues.push(...cycleErrors(referencesByAsset));
+    return issues;
+}
+/** DFS cycle detection with an explicit stack path; each cycle reported once. */
+function cycleErrors(referencesByAsset) {
+    const issues = [];
+    const finished = new Set();
+    const reportedCycles = new Set();
+    const stack = [];
+    const onStack = new Set();
+    function visit(assetId) {
+        if (finished.has(assetId))
+            return;
+        if (onStack.has(assetId)) {
+            const cyclePath = [...stack.slice(stack.indexOf(assetId)), assetId];
+            // Canonical key so `a → b → a` and `b → a → b` report once.
+            const cycleKey = [...new Set(cyclePath)].sort().join('\u0000');
+            if (!reportedCycles.has(cycleKey)) {
+                reportedCycles.add(cycleKey);
+                issues.push({
+                    assetId: cyclePath[0],
+                    message: `Reference cycle: ${cyclePath.map((id) => `"${id}"`).join(' → ')} — references express composition and must stay acyclic.`
+                });
+            }
+            return;
+        }
+        stack.push(assetId);
+        onStack.add(assetId);
+        for (const reference of referencesByAsset[assetId] ?? []) {
+            if (Object.hasOwn(referencesByAsset, reference.assetId))
+                visit(reference.assetId);
+        }
+        stack.pop();
+        onStack.delete(assetId);
+        finished.add(assetId);
+    }
+    for (const assetId of Object.keys(referencesByAsset))
+        visit(assetId);
+    return issues;
+}
+/**
+ * The transitive reference closure of a set of assets, including the starting
+ * set — the assets that must be delivered so the starting set renders as
+ * authored. Tolerates cycles and ignores dangling targets (both are reported
+ * as errors by `referenceErrors`).
+ */
+export function referenceClosure(assetIds, referencesByAsset) {
+    const closure = new Set();
+    const pending = [...assetIds];
+    while (pending.length > 0) {
+        const assetId = pending.pop();
+        if (closure.has(assetId) || !Object.hasOwn(referencesByAsset, assetId))
+            continue;
+        closure.add(assetId);
+        for (const reference of referencesByAsset[assetId]) {
+            pending.push(reference.assetId);
+        }
+    }
+    return closure;
+}
+/**
+ * A dependencies-first order over `assetIds` and everything they transitively
+ * reference — the build order that lets each entry inline its references from
+ * already-built entries. Throws on a cycle (with the cycle path).
+ */
+export function topologicalReferenceOrder(assetIds, referencesByAsset) {
+    const order = [];
+    const finished = new Set();
+    const stack = [];
+    const onStack = new Set();
+    function visit(assetId) {
+        if (finished.has(assetId) || !Object.hasOwn(referencesByAsset, assetId))
+            return;
+        if (onStack.has(assetId)) {
+            const cyclePath = [...stack.slice(stack.indexOf(assetId)), assetId];
+            throw new Error(`Reference cycle: ${cyclePath.map((id) => `"${id}"`).join(' → ')} — cannot order entries.`);
+        }
+        stack.push(assetId);
+        onStack.add(assetId);
+        for (const reference of referencesByAsset[assetId]) {
+            visit(reference.assetId);
+        }
+        stack.pop();
+        onStack.delete(assetId);
+        finished.add(assetId);
+        order.push(assetId);
+    }
+    for (const assetId of assetIds)
+        visit(assetId);
+    return order;
+}

package/dist/core/slice-data.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The slice data model keeps the source image separate from slicing metadata
+ * (Fundus tracks raw files and
+ * proxy dimensions separately), so there is no `SliceSource` here.
+ *
+ * The geometry is stored as **insets** (border thickness in source pixels), the
+ * canonical, render-ready form — equivalent to CSS `border-image-slice`.
+ * `slicedAxesFor` is the single source of truth for which axes each mode uses.
+ */
+export declare const SLICE_MODES: readonly ["nine", "three-horizontal", "three-vertical", "one"];
+export type SliceMode = (typeof SLICE_MODES)[number];
+/** Border thickness in source pixels. Always integers (pixel-precise). */
+export interface SliceInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Full slicing description for an image, independent of which image it applies
+ * to. Stored in the library as (part of) the slice plugin's parameters and
+ * emitted into generated manifest entries.
+ */
+export interface Slicing {
+    mode: SliceMode;
+    insets: SliceInsets;
+    /**
+     * Source pixels per CSS pixel — the scale the asset was exported at
+     * (`1` = @1x, `2` = @2x, `3` = @3x). All fixed slice dimensions (9-slice
+     * corners) are divided by this when rendering, so a high-resolution asset
+     * displays at its intended logical size.
+     */
+    pixelRatio: number;
+    /**
+     * Per-side thickness (in source pixels) of the image's baked-in overdraw — a
+     * drop shadow / glow painted around the actual element. The renderers treat
+     * the image **minus** the overdraw as the element: that core fills the layout
+     * box, and the overdraw band is painted outside it (like a CSS `box-shadow`).
+     * Optional: absent means no overdraw.
+     */
+    overdraw?: SliceInsets;
+}
+/** All-zero insets — the "no overdraw" value. */
+export declare function createZeroInsets(): SliceInsets;
+/**
+ * Default insets for a freshly ingested image: each border a quarter of the
+ * corresponding dimension (at least 1px where the image is large enough),
+ * always clamped so a center of at least one source pixel remains on each
+ * axis. For an axis too small for insets + a 1px center (width/height ≤ 2)
+ * the insets on that axis are 0 — structurally valid slicing for any size ≥ 1.
+ */
+export declare function defaultInsetsForSize(width: number, height: number): SliceInsets;
+/** Which source-image axes are sliced for a mode. */
+export declare function slicedAxesFor(mode: SliceMode): {
+    horizontal: boolean;
+    vertical: boolean;
+};
+/** Maximum inset on one side while preserving the opposite inset. */
+export declare function maxInset(insets: SliceInsets, side: keyof SliceInsets, width: number, height: number): number;
+/** Maximum overdraw on one side while preserving at least one core source pixel. */
+export declare function maxOverdraw(overdraw: SliceInsets, side: keyof SliceInsets, width: number, height: number): number;

package/dist/core/slice-data.js

@@ -0,0 +1,49 @@
+/**
+ * The slice data model keeps the source image separate from slicing metadata
+ * (Fundus tracks raw files and
+ * proxy dimensions separately), so there is no `SliceSource` here.
+ *
+ * The geometry is stored as **insets** (border thickness in source pixels), the
+ * canonical, render-ready form — equivalent to CSS `border-image-slice`.
+ * `slicedAxesFor` is the single source of truth for which axes each mode uses.
+ */
+export const SLICE_MODES = ['nine', 'three-horizontal', 'three-vertical', 'one'];
+/** All-zero insets — the "no overdraw" value. */
+export function createZeroInsets() {
+    return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+/**
+ * Default insets for a freshly ingested image: each border a quarter of the
+ * corresponding dimension (at least 1px where the image is large enough),
+ * always clamped so a center of at least one source pixel remains on each
+ * axis. For an axis too small for insets + a 1px center (width/height ≤ 2)
+ * the insets on that axis are 0 — structurally valid slicing for any size ≥ 1.
+ */
+export function defaultInsetsForSize(width, height) {
+    // max(1, quarter) is the desired border; min(…, floor((size − 1) / 2)) caps
+    // it so `2 × inset ≤ size − 1`, i.e. the center keeps ≥ 1 source pixel.
+    const horizontal = Math.min(Math.max(1, Math.floor(width / 4)), Math.floor((width - 1) / 2));
+    const vertical = Math.min(Math.max(1, Math.floor(height / 4)), Math.floor((height - 1) / 2));
+    return { top: vertical, right: horizontal, bottom: vertical, left: horizontal };
+}
+/** Which source-image axes are sliced for a mode. */
+export function slicedAxesFor(mode) {
+    return {
+        horizontal: mode === 'nine' || mode === 'three-horizontal',
+        vertical: mode === 'nine' || mode === 'three-vertical'
+    };
+}
+/** Maximum inset on one side while preserving the opposite inset. */
+export function maxInset(insets, side, width, height) {
+    if (side === 'left')
+        return width - insets.right;
+    if (side === 'right')
+        return width - insets.left;
+    if (side === 'top')
+        return height - insets.bottom;
+    return height - insets.top;
+}
+/** Maximum overdraw on one side while preserving at least one core source pixel. */
+export function maxOverdraw(overdraw, side, width, height) {
+    return maxInset(overdraw, side, width, height) - 1;
+}

package/dist/runtime/chroma-key-gl.d.ts

@@ -1,23 +1,41 @@
-import { ChromaKeyParameters } from "#fundus/core";
-
-//#region src/chroma-key-gl.d.ts
-declare class ChromaKeyGl {
-  #private;
-  /** Returns null when WebGL2 is unavailable or the shader fails to compile. */
-  static create(canvas: HTMLCanvasElement): ChromaKeyGl | null;
-  private constructor();
-  /**
-   * Set (or clear) the grayscale shape mask multiplied onto the output alpha. The
-   * mask is stretched over the full video frame, so author it at the video's aspect
-   * ratio. Pass null to remove the mask.
-   */
-  setMask(image: TexImageSource | null): void;
-  /**
-   * Upload the video's current frame and render it keyed. Sizes the drawing buffer to
-   * the video's intrinsic size on first draw (and after a size change).
-   */
-  draw(video: HTMLVideoElement, parameters: ChromaKeyParameters): void;
-  dispose(): void;
+/**
+ * WebGL2 chroma-key video renderer based on the public UnityChromakey shader
+ * (https://github.com/otdavies/UnityChromakey, `Shaders/ChromaKey.shader`) so a
+ * greenscreen video plays with a transparent background.
+ *
+ * The keying algorithm follows the upstream shader: the key color and each
+ * pixel are converted to YCbCr chroma (Cb/Cr), the squared chroma distance is mapped
+ * through a cutoff/feather window (`colorclose`), the resulting mask is blurred with a
+ * 3×3 neighbourhood + smoothstep-sharpened, the keyed color is despilled (green pulled
+ * toward the red/blue average, lost luminance re-added), and the output is
+ * `vec4(color * mask, mask)` — the upstream output formula (tint fixed at white; tinting
+ * is host styling, not asset data) — emitted premultiplied (rgb × alpha) for the canvas
+ * compositor (see the fragColor note).
+ *
+ * Fundus adds an optional mask pass (`setMask`): a grayscale image
+ * sampled at the same UVs whose luminance multiplies the final alpha — white keeps a
+ * pixel, black drops it, gray fades it (no alpha clip). Absent a mask, a 1×1 white
+ * fallback texture makes the pass a no-op.
+ *
+ * Owns its own GL context on the given canvas. `create` returns null when WebGL2 is
+ * unavailable. Browser-only; the caller drives it per frame with the playing <video>.
+ */
+import type { ChromaKeyParameters } from '../core/index.js';
+export declare class ChromaKeyGl {
+    #private;
+    /** Returns null when WebGL2 is unavailable or the shader fails to compile. */
+    static create(canvas: HTMLCanvasElement): ChromaKeyGl | null;
+    private constructor();
+    /**
+     * Set (or clear) the grayscale shape mask multiplied onto the output alpha. The
+     * mask is stretched over the full video frame, so author it at the video's aspect
+     * ratio. Pass null to remove the mask.
+     */
+    setMask(image: TexImageSource | null): void;
+    /**
+     * Upload the video's current frame and render it keyed. Sizes the drawing buffer to
+     * the video's intrinsic size on first draw (and after a size change).
+     */
+    draw(video: HTMLVideoElement, parameters: ChromaKeyParameters): void;
+    dispose(): void;
 }
-//#endregion
-export { ChromaKeyGl };