@farm.js/scripts 0.1.0-beta.0

package/dist/config.js

@@ -0,0 +1,68 @@
+import { cloneScriptDefinition, readScriptHandle } from "./shared.js";
+export function resolveScriptsOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("scripts options must be an object");
+    }
+    if ("enabled" in options) {
+        throw new TypeError("scripts does not accept enabled; remove scripts() from plugins to disable it");
+    }
+    if (!Array.isArray(options.scripts) || options.scripts.length === 0) {
+        throw new TypeError("scripts requires at least one defineScript() handle");
+    }
+    const definitions = [];
+    const names = new Map();
+    const sources = new Map();
+    for (const handle of options.scripts) {
+        const marked = readScriptHandle(handle);
+        if (!marked) {
+            throw new TypeError("scripts entries must come from defineScript() in @farm.js/scripts/client");
+        }
+        const definition = cloneScriptDefinition(marked);
+        if (names.has(definition.name)) {
+            throw new TypeError(`scripts contains duplicate name ${JSON.stringify(definition.name)}`);
+        }
+        const sourceOwner = sources.get(definition.src);
+        if (sourceOwner) {
+            throw new TypeError(`scripts ${JSON.stringify(sourceOwner)} and ${JSON.stringify(definition.name)} use the same src; use one typed handle for that vendor script`);
+        }
+        names.set(definition.name, definition);
+        sources.set(definition.src, definition.name);
+        definitions.push(definition);
+    }
+    for (const definition of definitions) {
+        for (const dependency of definition.dependsOn) {
+            if (dependency === definition.name) {
+                throw new TypeError(`script ${JSON.stringify(definition.name)} cannot depend on itself`);
+            }
+            if (!names.has(dependency)) {
+                throw new TypeError(`script ${JSON.stringify(definition.name)} depends on unregistered script ${JSON.stringify(dependency)}`);
+            }
+        }
+    }
+    assertAcyclicDependencies(names);
+    return Object.freeze({
+        scripts: Object.freeze(definitions),
+        basePath: "/",
+    });
+}
+function assertAcyclicDependencies(definitions) {
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(name, path) {
+        if (visited.has(name))
+            return;
+        if (visiting.has(name)) {
+            const start = path.indexOf(name);
+            const cycle = [...path.slice(start), name];
+            throw new TypeError(`scripts dependency cycle: ${cycle.join(" -> ")}`);
+        }
+        visiting.add(name);
+        const definition = definitions.get(name);
+        for (const dependency of definition.dependsOn)
+            visit(dependency, [...path, name]);
+        visiting.delete(name);
+        visited.add(name);
+    }
+    for (const name of definitions.keys())
+        visit(name, []);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type FarmPlugin } from "@farm.js/core/plugin";
+import type { ResolvedScriptsOptions, ScriptRuntime, ScriptsOptions } from "./types.js";
+export type { AnyScriptHandle, ResolvedScriptDefinition, ResolvedScriptLoadStrategy, ScriptConsentState, ScriptDefinition, ScriptDuration, ScriptHandle, ScriptLoadStrategy, ScriptPlacement, ScriptSnapshot, ScriptStatus, ScriptStatusListener, ScriptType, ScriptsOptions, } from "./types.js";
+/** Manage explicitly registered third-party browser scripts across Farm's client lifecycle. */
+export declare function scripts(options: ScriptsOptions): FarmPlugin<unknown, Record<string, unknown>, ScriptRuntime, ResolvedScriptsOptions>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExF,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,+FAA+F;AAC/F,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,uFA0C9C"}

package/dist/index.js

@@ -0,0 +1,43 @@
+import { definePlugin } from "@farm.js/core/plugin";
+import { resolveScriptsOptions } from "./config.js";
+import { normalizeScriptBasePath } from "./shared.js";
+/** Manage explicitly registered third-party browser scripts across Farm's client lifecycle. */
+export function scripts(options) {
+    const resolved = resolveScriptsOptions(options);
+    const publicConfig = {
+        scripts: resolved.scripts,
+        basePath: resolved.basePath,
+    };
+    let plugin;
+    plugin = definePlugin({
+        name: "farm:scripts",
+        enforce: "post",
+        configure(config) {
+            publicConfig.basePath = normalizeScriptBasePath(config.basePath);
+            if ((config.plugins ?? []).filter((candidate) => candidate.name === "farm:scripts").length > 1) {
+                throw new Error("[farm:scripts] Configure all browser scripts in one scripts() instance");
+            }
+        },
+        client: {
+            public: publicConfig,
+            async setup({ public: config }) {
+                const runtime = await import("@farm.js/scripts/client");
+                return runtime.startScriptRuntime(config.scripts, window, config.basePath);
+            },
+            hydration: {
+                after({ state }) {
+                    state.afterHydration();
+                },
+            },
+            navigation: {
+                rendered({ state }) {
+                    state.refresh();
+                },
+            },
+            close({ state }) {
+                state.close();
+            },
+        },
+    });
+    return plugin;
+}

package/dist/shared.d.ts

@@ -0,0 +1,18 @@
+import type { AnyScriptHandle, ResolvedScriptDefinition, ScriptDefinition, ScriptDependency, ScriptDuration, ScriptHandle } from "./types.js";
+export declare const FARM_SCRIPT_HANDLE: unique symbol;
+interface MarkedScriptHandle {
+    readonly [FARM_SCRIPT_HANDLE]: Readonly<ResolvedScriptDefinition>;
+}
+export declare function markScriptHandle<T>(handle: ScriptHandle<T>, definition: ResolvedScriptDefinition): ScriptHandle<T>;
+export declare function readScriptHandle(value: unknown): Readonly<ResolvedScriptDefinition> | undefined;
+export declare function normalizeScriptDefinition(input: ScriptDefinition): ResolvedScriptDefinition;
+export declare function cloneScriptDefinition(definition: Readonly<ResolvedScriptDefinition>): ResolvedScriptDefinition;
+export declare function sameScriptDefinition(left: Readonly<ResolvedScriptDefinition>, right: Readonly<ResolvedScriptDefinition>): boolean;
+export declare function scriptHandleName(value: ScriptDependency): string;
+export declare function parseScriptDuration(value: ScriptDuration, label: string, allowZero: boolean): number;
+export declare function validateGlobalPath(value: unknown): string;
+export declare function isMarkedScriptHandle(value: unknown): value is AnyScriptHandle & MarkedScriptHandle;
+export declare function normalizeScriptBasePath(value: unknown): string;
+export declare function withScriptBasePath(source: string, basePath: string): string;
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EAExB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,kBAAkB,eAAwC,CAAC;AAgBxE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAAC;CACnE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,UAAU,EAAE,wBAAwB,GACnC,YAAY,CAAC,CAAC,CAAC,CAQjB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAK/F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,gBAAgB,GAAG,wBAAwB,CA2E3F;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GAC7C,wBAAwB,CAO1B;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EACxC,KAAK,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GACxC,OAAO,CAET;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOhE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,MAAM,CAsBR;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,eAAe,GAAG,kBAAkB,CAE/C;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM3E"}

package/dist/shared.js

@@ -0,0 +1,272 @@
+export const FARM_SCRIPT_HANDLE = Symbol.for("@farm.js/scripts.handle");
+const SAFE_GLOBAL_SEGMENT = /^[A-Za-z_$][\w$]*$/;
+const UNSAFE_GLOBAL_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+const REFERRER_POLICIES = new Set([
+    "",
+    "no-referrer",
+    "no-referrer-when-downgrade",
+    "origin",
+    "origin-when-cross-origin",
+    "same-origin",
+    "strict-origin",
+    "strict-origin-when-cross-origin",
+    "unsafe-url",
+]);
+export function markScriptHandle(handle, definition) {
+    Object.defineProperty(handle, FARM_SCRIPT_HANDLE, {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+        value: definition,
+    });
+    return handle;
+}
+export function readScriptHandle(value) {
+    if (!value || (typeof value !== "object" && typeof value !== "function"))
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(value, FARM_SCRIPT_HANDLE);
+    if (!descriptor || !("value" in descriptor))
+        return undefined;
+    return descriptor.value;
+}
+export function normalizeScriptDefinition(input) {
+    if (!isPlainObject(input))
+        throw new TypeError("script definition must be an object");
+    const name = normalizeText(input.name, "name");
+    if ([...name].some((character) => character.charCodeAt(0) <= 31 || character.charCodeAt(0) === 127)) {
+        throw new TypeError("script name cannot contain control characters");
+    }
+    const src = normalizeScriptSource(input.src);
+    const global = input.global === undefined ? undefined : validateGlobalPath(input.global);
+    const load = normalizeLoadStrategy(input.load);
+    const consent = input.consent === undefined ? undefined : normalizeText(input.consent, "consent category");
+    const dependsOn = normalizeDependencies(input.dependsOn);
+    const type = input.type ?? "classic";
+    if (type !== "classic" && type !== "module") {
+        throw new TypeError('script type must be "classic" or "module"');
+    }
+    const placement = input.placement ?? "head";
+    if (placement !== "head" && placement !== "body") {
+        throw new TypeError('script placement must be "head" or "body"');
+    }
+    assertBoolean(input.async, "async");
+    assertBoolean(input.preconnect, "preconnect");
+    const retries = input.retries ?? 0;
+    if (!Number.isInteger(retries) || retries < 0 || retries > 10) {
+        throw new TypeError("script retries must be an integer from 0 to 10");
+    }
+    const crossOrigin = input.crossOrigin;
+    if (crossOrigin !== undefined &&
+        crossOrigin !== "anonymous" &&
+        crossOrigin !== "use-credentials") {
+        throw new TypeError('script crossOrigin must be "anonymous" or "use-credentials"');
+    }
+    if (input.referrerPolicy !== undefined && !REFERRER_POLICIES.has(input.referrerPolicy)) {
+        throw new TypeError("script referrerPolicy is not a supported browser referrer policy");
+    }
+    if (input.fetchPriority !== undefined &&
+        input.fetchPriority !== "high" &&
+        input.fetchPriority !== "low" &&
+        input.fetchPriority !== "auto") {
+        throw new TypeError('script fetchPriority must be "high", "low", or "auto"');
+    }
+    const definition = {
+        name,
+        src,
+        load,
+        dependsOn,
+        type,
+        placement,
+        async: input.async ?? true,
+        timeoutMs: parseScriptDuration(input.timeout ?? "15s", "timeout", false),
+        readyTimeoutMs: parseScriptDuration(input.readyTimeout ?? "1s", "readyTimeout", true),
+        retries,
+        retryDelayMs: parseScriptDuration(input.retryDelay ?? 250, "retryDelay", true),
+        preconnect: input.preconnect ?? false,
+        attributes: normalizeDataAttributes(input.attributes),
+        ...(global ? { global } : {}),
+        ...(consent ? { consent } : {}),
+        ...(input.id === undefined ? {} : { id: normalizeText(input.id, "id") }),
+        ...(input.integrity === undefined
+            ? {}
+            : { integrity: normalizeText(input.integrity, "integrity") }),
+        ...(crossOrigin ? { crossOrigin } : {}),
+        ...(input.referrerPolicy === undefined ? {} : { referrerPolicy: input.referrerPolicy }),
+        ...(input.fetchPriority === undefined ? {} : { fetchPriority: input.fetchPriority }),
+    };
+    return deepFreezeDefinition(definition);
+}
+export function cloneScriptDefinition(definition) {
+    return deepFreezeDefinition({
+        ...definition,
+        load: typeof definition.load === "object" ? { ...definition.load } : definition.load,
+        dependsOn: [...definition.dependsOn],
+        attributes: { ...definition.attributes },
+    });
+}
+export function sameScriptDefinition(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function scriptHandleName(value) {
+    if (typeof value === "string")
+        return normalizeText(value, "dependency");
+    const definition = readScriptHandle(value);
+    if (!definition) {
+        throw new TypeError("script dependency must be a script name or a defineScript() handle");
+    }
+    return definition.name;
+}
+export function parseScriptDuration(value, label, allowZero) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || value < 0 || (!allowZero && value === 0)) {
+            throw new TypeError(`script ${label} must be ${allowZero ? "a non-negative" : "a positive"} finite duration`);
+        }
+        return value;
+    }
+    if (typeof value !== "string") {
+        throw new TypeError(`script ${label} must be a number or duration string`);
+    }
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(value);
+    if (!match) {
+        throw new TypeError(`script ${label} must use a duration such as "250ms", "5s", or "1m"`);
+    }
+    const amount = Number(match[1]);
+    if (!allowZero && amount === 0) {
+        throw new TypeError(`script ${label} must be a positive duration`);
+    }
+    const multiplier = match[2] === "ms" ? 1 : match[2] === "s" ? 1_000 : 60_000;
+    return amount * multiplier;
+}
+export function validateGlobalPath(value) {
+    const path = normalizeText(value, "global");
+    const segments = path.split(".");
+    if (segments[0] === "window" || segments[0] === "globalThis" || segments[0] === "self") {
+        throw new TypeError(`script global is relative to window; use ${JSON.stringify(segments.slice(1).join("."))}`);
+    }
+    if (segments.some((segment) => !SAFE_GLOBAL_SEGMENT.test(segment) || UNSAFE_GLOBAL_SEGMENTS.has(segment.toLowerCase()))) {
+        throw new TypeError(`script global must be a safe dotted path, received ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+export function isMarkedScriptHandle(value) {
+    return readScriptHandle(value) !== undefined;
+}
+export function normalizeScriptBasePath(value) {
+    if (typeof value !== "string" || !value.trim() || value === "/")
+        return "/";
+    return `/${value.replace(/^\/+|\/+$/g, "")}`;
+}
+export function withScriptBasePath(source, basePath) {
+    if (!source.startsWith("/") || source.startsWith("//"))
+        return source;
+    const normalizedBase = normalizeScriptBasePath(basePath);
+    if (normalizedBase === "/")
+        return source;
+    if (source === normalizedBase || source.startsWith(`${normalizedBase}/`))
+        return source;
+    return `${normalizedBase}${source}`;
+}
+function normalizeLoadStrategy(value) {
+    const strategy = value ?? "after-hydration";
+    if (strategy === "immediate" ||
+        strategy === "after-hydration" ||
+        strategy === "idle" ||
+        strategy === "interaction" ||
+        strategy === "manual") {
+        return strategy;
+    }
+    if (!isPlainObject(strategy) || strategy.when !== "visible") {
+        throw new TypeError('script load must be "immediate", "after-hydration", "idle", "interaction", "manual", or a visible trigger');
+    }
+    return Object.freeze({
+        when: "visible",
+        selector: normalizeText(strategy.selector, "visible selector"),
+        rootMargin: strategy.rootMargin === undefined
+            ? "200px"
+            : normalizeText(strategy.rootMargin, "visible rootMargin"),
+    });
+}
+function normalizeDependencies(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError("script dependsOn must be an array");
+    return [...new Set(value.map(scriptHandleName))];
+}
+function normalizeScriptSource(value) {
+    const src = normalizeText(value, "src");
+    const rootRelative = src.startsWith("/") && !src.startsWith("//");
+    if (rootRelative) {
+        const hasControlCharacter = Array.from(src).some((character) => {
+            const code = character.charCodeAt(0);
+            return code <= 31 || code === 127;
+        });
+        if (src.includes("\\") || hasControlCharacter) {
+            throw new TypeError("script root-relative src cannot contain backslashes or control characters");
+        }
+        return src;
+    }
+    if (!/^https?:\/\//i.test(src)) {
+        throw new TypeError("script src must be root-relative or use an absolute HTTP(S) URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(src);
+    }
+    catch {
+        throw new TypeError(`script src must be a valid URL, received ${JSON.stringify(src)}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new TypeError("script src must use HTTP(S)");
+    }
+    if (parsed.username || parsed.password) {
+        throw new TypeError("script src cannot contain URL credentials");
+    }
+    return src;
+}
+function normalizeDataAttributes(value) {
+    if (value === undefined)
+        return {};
+    if (!isPlainObject(value))
+        throw new TypeError("script attributes must be a plain object");
+    const result = {};
+    for (const [key, attributeValue] of Object.entries(value)) {
+        if (!/^data-[a-z0-9_.:-]+$/i.test(key)) {
+            throw new TypeError(`script attribute ${JSON.stringify(key)} must be a data-* attribute`);
+        }
+        if (key.toLowerCase().startsWith("data-farm-script")) {
+            throw new TypeError(`script attribute ${JSON.stringify(key)} is reserved by @farm.js/scripts`);
+        }
+        if (typeof attributeValue !== "string" &&
+            typeof attributeValue !== "number" &&
+            typeof attributeValue !== "boolean") {
+            throw new TypeError(`script attribute ${JSON.stringify(key)} must be a string, number, or boolean`);
+        }
+        result[key] = String(attributeValue);
+    }
+    return result;
+}
+function normalizeText(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError(`script ${label} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function assertBoolean(value, label) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError(`script ${label} must be boolean`);
+    }
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function deepFreezeDefinition(definition) {
+    if (typeof definition.load === "object")
+        Object.freeze(definition.load);
+    Object.freeze(definition.dependsOn);
+    Object.freeze(definition.attributes);
+    return Object.freeze(definition);
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+export type ScriptDuration = number | `${number}${"ms" | "s" | "m"}`;
+export type ScriptLoadStrategy = "immediate" | "after-hydration" | "idle" | "interaction" | "manual" | {
+    when: "visible";
+    selector: string;
+    rootMargin?: string;
+};
+export type ScriptStatus = "idle" | "blocked" | "loading" | "ready" | "error";
+export type ScriptConsentState = "unknown" | "granted" | "denied";
+export type ScriptPlacement = "head" | "body";
+export type ScriptType = "classic" | "module";
+export interface ScriptSnapshot {
+    name: string;
+    status: ScriptStatus;
+    attempt: number;
+    error?: unknown;
+}
+export type ScriptStatusListener = (snapshot: Readonly<ScriptSnapshot>) => void;
+export interface ScriptHandle<T = unknown> {
+    /** Stable registry name chosen by the application. */
+    readonly name: string;
+    /** Normalized, browser-safe definition used by the Farm plugin. */
+    readonly definition: Readonly<ResolvedScriptDefinition>;
+    /** Current browser loading state. SSR reads return `idle`. */
+    readonly status: ScriptStatus;
+    /** Last terminal loading error, when status is `error`. */
+    readonly error: unknown;
+    /** Load the external script and resolve its configured global. */
+    load(): Promise<T>;
+    /** Run code with the resolved SDK after it becomes ready. */
+    use<TResult>(callback: (sdk: T) => TResult | PromiseLike<TResult>): Promise<Awaited<TResult>>;
+    /** Observe state changes. The listener is called immediately in the browser. */
+    subscribe(listener: ScriptStatusListener): () => void;
+}
+export type AnyScriptHandle = ScriptHandle<any>;
+export type ScriptDependency = string | AnyScriptHandle;
+export interface ScriptDefinition {
+    /** Stable registry name. Local variable names can be different. */
+    name: string;
+    /** Root-relative or HTTP(S) script URL. */
+    src: string;
+    /** Safe dotted global path created by the loaded script, such as `mixpanel` or `google.maps`. */
+    global?: string;
+    /** When Farm should request the script. Defaults to `after-hydration`. */
+    load?: ScriptLoadStrategy;
+    /** Consent category that must be explicitly granted before loading. */
+    consent?: string;
+    /** Scripts that must become ready before this script starts loading. */
+    dependsOn?: readonly ScriptDependency[];
+    /** Script execution type. Defaults to `classic`. */
+    type?: ScriptType;
+    /** DOM destination for the generated element. Defaults to `head`. */
+    placement?: ScriptPlacement;
+    /** Dynamic script async behavior. Defaults to true. */
+    async?: boolean;
+    /** Network loading timeout. Numbers are milliseconds. Defaults to 15s. */
+    timeout?: ScriptDuration;
+    /** How long to wait for `global` after the script load event. Defaults to 1s. */
+    readyTimeout?: ScriptDuration;
+    /** Additional loading attempts after the first failure. Defaults to 0. */
+    retries?: number;
+    /** Delay between loading attempts. Numbers are milliseconds. Defaults to 250ms. */
+    retryDelay?: ScriptDuration;
+    /** Add a preconnect hint for a cross-origin script when the client runtime starts. */
+    preconnect?: boolean;
+    /** Optional element ID. */
+    id?: string;
+    /** Subresource Integrity value supplied by the script provider. */
+    integrity?: string;
+    /** CORS mode used by the script request. */
+    crossOrigin?: "anonymous" | "use-credentials";
+    /** Referrer policy used by the script request. */
+    referrerPolicy?: ReferrerPolicy;
+    /** Fetch priority hint. */
+    fetchPriority?: "high" | "low" | "auto";
+    /** Vendor-specific `data-*` attributes. */
+    attributes?: Readonly<Record<`data-${string}`, string | number | boolean>>;
+}
+export interface ResolvedVisibleScriptLoadStrategy {
+    when: "visible";
+    selector: string;
+    rootMargin: string;
+}
+export type ResolvedScriptLoadStrategy = Exclude<ScriptLoadStrategy, {
+    when: "visible";
+}> | ResolvedVisibleScriptLoadStrategy;
+export interface ResolvedScriptDefinition {
+    name: string;
+    src: string;
+    global?: string;
+    load: ResolvedScriptLoadStrategy;
+    consent?: string;
+    dependsOn: string[];
+    type: ScriptType;
+    placement: ScriptPlacement;
+    async: boolean;
+    timeoutMs: number;
+    readyTimeoutMs: number;
+    retries: number;
+    retryDelayMs: number;
+    preconnect: boolean;
+    id?: string;
+    integrity?: string;
+    crossOrigin?: "anonymous" | "use-credentials";
+    referrerPolicy?: ReferrerPolicy;
+    fetchPriority?: "high" | "low" | "auto";
+    attributes: Record<string, string>;
+}
+export interface ScriptsOptions {
+    scripts: readonly AnyScriptHandle[];
+}
+export interface ResolvedScriptsOptions {
+    scripts: ResolvedScriptDefinition[];
+    basePath: string;
+}
+export interface ScriptRuntime {
+    afterHydration(): void;
+    refresh(): void;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@farm.js/scripts",
+  "version": "0.1.0-beta.0",
+  "description": "Typed, lifecycle-aware third-party browser scripts for Farm.js",
+  "keywords": [
+    "consent",
+    "farm.js",
+    "script-loader",
+    "third-party",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-scripts"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.92"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}