@joycostudio/iris 0.0.0-stage → 0.0.1

package/dist/policy-types-LoD2Ldcl.d.cts

@@ -0,0 +1,147 @@
+/** Metadata shared by asset providers. No framework or encoder dependencies. */
+type IrisVariant = {
+    url: string;
+    width: number;
+    height: number;
+    bytes: number;
+    format?: string;
+    progressive?: boolean;
+    alpha?: boolean;
+    animated?: boolean;
+};
+type IrisPlaceholderOptions = {
+    blur?: number;
+    width?: number;
+    quality?: number;
+};
+type IrisPlaceholderVariant = {
+    width: number;
+    quality: number;
+    url: string;
+};
+type IrisCatalogAsset = Omit<IrisVariant, "url"> & {
+    id?: string;
+    src: string;
+    variants?: readonly IrisVariant[];
+    placeholder?: string;
+    placeholders?: readonly IrisPlaceholderVariant[];
+};
+type IrisAssetInput = string | {
+    src: string;
+    id?: string;
+    variants?: readonly (string | IrisVariant)[];
+    placeholder?: string;
+    placeholders?: readonly IrisPlaceholderVariant[];
+};
+type IrisPolicyUsage<Custom = Record<string, unknown>> = {
+    /** CSS/logical pixels; omit when the layout is not known yet. */
+    width?: number;
+    dpr?: number;
+    priority?: boolean;
+    tags?: readonly string[];
+    custom?: Custom;
+};
+type IrisPolicyContext<Custom = Record<string, unknown>> = {
+    src: string;
+    asset: Readonly<IrisCatalogAsset>;
+    variants: readonly IrisVariant[];
+    usage: Readonly<IrisPolicyUsage<Custom>>;
+};
+type IrisMatcher<Custom = Record<string, unknown>> = string | RegExp | ((context: IrisPolicyContext<Custom>) => boolean);
+type IrisRange = {
+    min?: number;
+    max?: number;
+};
+type IrisConditions = {
+    sourceBytes?: IrisRange;
+    sourceWidth?: IrisRange;
+    renderedWidth?: IrisRange;
+    targetWidth?: IrisRange;
+    alpha?: boolean;
+    priority?: boolean;
+    format?: string;
+};
+type IrisRecipe = {
+    placeholder?: "none" | "blur" | IrisPlaceholderOptions;
+    preview?: "none" | {
+        /** Fraction of the final width selected by the browser, strictly between 0 and 1. */
+        ratio?: number;
+        /** Upper bound, also applied when ratio is supplied. */
+        maxWidth?: number;
+        /** Next image quality for a distinct, smaller preview file. */
+        quality?: number;
+        url?: string;
+        /** Load the final image after the preview has appeared. */
+        loadFirst?: boolean;
+        /** Minimum time to show the preview before starting the final request. */
+        minDisplayMs?: number;
+    };
+};
+type IrisPolicyRecipe<Custom = Record<string, unknown>> = IrisRecipe | ((context: IrisPolicyContext<Custom>) => IrisRecipe);
+type IrisRule<Custom = Record<string, unknown>> = {
+    include?: IrisMatcher<Custom> | readonly IrisMatcher<Custom>[];
+    exclude?: IrisMatcher<Custom> | readonly IrisMatcher<Custom>[];
+    when?: IrisConditions | ((context: IrisPolicyContext<Custom>) => boolean);
+    recipe: string;
+};
+type IrisPolicyOptions<Custom = Record<string, unknown>> = {
+    assets?: readonly (IrisAssetInput | IrisCatalogAsset)[];
+    recipes: Readonly<Record<string, IrisPolicyRecipe<Custom>>>;
+    rules?: readonly IrisRule<Custom>[];
+    fallback: string;
+};
+type IrisPolicyDiagnostic = {
+    code: "missing_preview" | "missing_placeholder" | "missing_variant" | "undersized_final" | "unknown_target";
+    message: string;
+};
+type IrisResolvedPlan = {
+    src: string;
+    recipe: string;
+    /** null means explicit recipe or fallback; otherwise the matching rule index. */
+    ruleIndex: number | null;
+    targetWidth: number | null;
+    placeholder: {
+        url: string;
+        blur: number;
+    } | null;
+    preview: IrisVariant | null;
+    final: IrisVariant;
+    diagnostics: IrisPolicyDiagnostic[];
+};
+type IrisResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+type IrisResolveOptions<Custom = Record<string, unknown>> = {
+    asset: string | IrisCatalogAsset;
+    catalog?: readonly IrisCatalogAsset[];
+    usage?: IrisPolicyUsage<Custom>;
+    recipe?: string;
+};
+type IrisRecipeSelection = {
+    name: string;
+    ruleIndex: number | null;
+    recipe: IrisRecipe;
+};
+type IrisSelectOptions<Custom = Record<string, unknown>> = {
+    asset: IrisCatalogAsset;
+    usage?: IrisPolicyUsage<Custom>;
+    recipe?: string;
+};
+type IrisPolicy<Custom = Record<string, unknown>> = {
+    assets: readonly (IrisAssetInput | IrisCatalogAsset)[];
+    placeholderRequests: readonly {
+        width: number;
+        quality: number;
+    }[];
+    select: (options: IrisSelectOptions<Custom>) => IrisResult<IrisRecipeSelection>;
+    resolve: (options: IrisResolveOptions<Custom>) => IrisResult<IrisResolvedPlan>;
+};
+
+export type { IrisPolicyOptions as I, IrisPolicy as a, IrisAssetInput as b, IrisCatalogAsset as c, IrisConditions as d, IrisMatcher as e, IrisPlaceholderOptions as f, IrisPlaceholderVariant as g, IrisPolicyContext as h, IrisPolicyDiagnostic as i, IrisPolicyRecipe as j, IrisPolicyUsage as k, IrisRange as l, IrisRecipe as m, IrisRecipeSelection as n, IrisResolveOptions as o, IrisResolvedPlan as p, IrisResult as q, IrisRule as r, IrisSelectOptions as s, IrisVariant as t };

package/dist/policy-types-LoD2Ldcl.d.ts

@@ -0,0 +1,147 @@
+/** Metadata shared by asset providers. No framework or encoder dependencies. */
+type IrisVariant = {
+    url: string;
+    width: number;
+    height: number;
+    bytes: number;
+    format?: string;
+    progressive?: boolean;
+    alpha?: boolean;
+    animated?: boolean;
+};
+type IrisPlaceholderOptions = {
+    blur?: number;
+    width?: number;
+    quality?: number;
+};
+type IrisPlaceholderVariant = {
+    width: number;
+    quality: number;
+    url: string;
+};
+type IrisCatalogAsset = Omit<IrisVariant, "url"> & {
+    id?: string;
+    src: string;
+    variants?: readonly IrisVariant[];
+    placeholder?: string;
+    placeholders?: readonly IrisPlaceholderVariant[];
+};
+type IrisAssetInput = string | {
+    src: string;
+    id?: string;
+    variants?: readonly (string | IrisVariant)[];
+    placeholder?: string;
+    placeholders?: readonly IrisPlaceholderVariant[];
+};
+type IrisPolicyUsage<Custom = Record<string, unknown>> = {
+    /** CSS/logical pixels; omit when the layout is not known yet. */
+    width?: number;
+    dpr?: number;
+    priority?: boolean;
+    tags?: readonly string[];
+    custom?: Custom;
+};
+type IrisPolicyContext<Custom = Record<string, unknown>> = {
+    src: string;
+    asset: Readonly<IrisCatalogAsset>;
+    variants: readonly IrisVariant[];
+    usage: Readonly<IrisPolicyUsage<Custom>>;
+};
+type IrisMatcher<Custom = Record<string, unknown>> = string | RegExp | ((context: IrisPolicyContext<Custom>) => boolean);
+type IrisRange = {
+    min?: number;
+    max?: number;
+};
+type IrisConditions = {
+    sourceBytes?: IrisRange;
+    sourceWidth?: IrisRange;
+    renderedWidth?: IrisRange;
+    targetWidth?: IrisRange;
+    alpha?: boolean;
+    priority?: boolean;
+    format?: string;
+};
+type IrisRecipe = {
+    placeholder?: "none" | "blur" | IrisPlaceholderOptions;
+    preview?: "none" | {
+        /** Fraction of the final width selected by the browser, strictly between 0 and 1. */
+        ratio?: number;
+        /** Upper bound, also applied when ratio is supplied. */
+        maxWidth?: number;
+        /** Next image quality for a distinct, smaller preview file. */
+        quality?: number;
+        url?: string;
+        /** Load the final image after the preview has appeared. */
+        loadFirst?: boolean;
+        /** Minimum time to show the preview before starting the final request. */
+        minDisplayMs?: number;
+    };
+};
+type IrisPolicyRecipe<Custom = Record<string, unknown>> = IrisRecipe | ((context: IrisPolicyContext<Custom>) => IrisRecipe);
+type IrisRule<Custom = Record<string, unknown>> = {
+    include?: IrisMatcher<Custom> | readonly IrisMatcher<Custom>[];
+    exclude?: IrisMatcher<Custom> | readonly IrisMatcher<Custom>[];
+    when?: IrisConditions | ((context: IrisPolicyContext<Custom>) => boolean);
+    recipe: string;
+};
+type IrisPolicyOptions<Custom = Record<string, unknown>> = {
+    assets?: readonly (IrisAssetInput | IrisCatalogAsset)[];
+    recipes: Readonly<Record<string, IrisPolicyRecipe<Custom>>>;
+    rules?: readonly IrisRule<Custom>[];
+    fallback: string;
+};
+type IrisPolicyDiagnostic = {
+    code: "missing_preview" | "missing_placeholder" | "missing_variant" | "undersized_final" | "unknown_target";
+    message: string;
+};
+type IrisResolvedPlan = {
+    src: string;
+    recipe: string;
+    /** null means explicit recipe or fallback; otherwise the matching rule index. */
+    ruleIndex: number | null;
+    targetWidth: number | null;
+    placeholder: {
+        url: string;
+        blur: number;
+    } | null;
+    preview: IrisVariant | null;
+    final: IrisVariant;
+    diagnostics: IrisPolicyDiagnostic[];
+};
+type IrisResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+type IrisResolveOptions<Custom = Record<string, unknown>> = {
+    asset: string | IrisCatalogAsset;
+    catalog?: readonly IrisCatalogAsset[];
+    usage?: IrisPolicyUsage<Custom>;
+    recipe?: string;
+};
+type IrisRecipeSelection = {
+    name: string;
+    ruleIndex: number | null;
+    recipe: IrisRecipe;
+};
+type IrisSelectOptions<Custom = Record<string, unknown>> = {
+    asset: IrisCatalogAsset;
+    usage?: IrisPolicyUsage<Custom>;
+    recipe?: string;
+};
+type IrisPolicy<Custom = Record<string, unknown>> = {
+    assets: readonly (IrisAssetInput | IrisCatalogAsset)[];
+    placeholderRequests: readonly {
+        width: number;
+        quality: number;
+    }[];
+    select: (options: IrisSelectOptions<Custom>) => IrisResult<IrisRecipeSelection>;
+    resolve: (options: IrisResolveOptions<Custom>) => IrisResult<IrisResolvedPlan>;
+};
+
+export type { IrisPolicyOptions as I, IrisPolicy as a, IrisAssetInput as b, IrisCatalogAsset as c, IrisConditions as d, IrisMatcher as e, IrisPlaceholderOptions as f, IrisPlaceholderVariant as g, IrisPolicyContext as h, IrisPolicyDiagnostic as i, IrisPolicyRecipe as j, IrisPolicyUsage as k, IrisRange as l, IrisRecipe as m, IrisRecipeSelection as n, IrisResolveOptions as o, IrisResolvedPlan as p, IrisResult as q, IrisRule as r, IrisSelectOptions as s, IrisVariant as t };