uncial-cms 0.0.0

package/dist/deploy-status.js

@@ -0,0 +1,118 @@
+/**
+ * Post-save deploy-status lifecycle (ticket 05, SPEC §6.6 / D5).
+ *
+ * After a save commits, the runtime polls `adapter.commitStatus(commitSha)` and
+ * surfaces the deploy lifecycle: `committed → building… → live` (or
+ * `build failed`, or a calm `status unknown` when the repo reports no checks).
+ * The timing constants live here; tests shrink them via injection.
+ */
+export const DEFAULT_DEPLOY_STATUS_TIMINGS = {
+    firstDelayMs: 3_000,
+    intervalMs: 10_000,
+    timeoutMs: 5 * 60_000
+};
+/** Map a forge commit status to a deploy phase and whether polling should stop. */
+export function deployPhaseForStatus(status) {
+    switch (status) {
+        case 'pending':
+            return { phase: 'building', done: false };
+        case 'success':
+            return { phase: 'live', done: true };
+        case 'failure':
+            return { phase: 'failed', done: true };
+        case 'unknown':
+        default:
+            // No CI configured (or the forge reports nothing): terminal and calm.
+            return { phase: 'unknown', done: true };
+    }
+}
+export function githubCommitUrl(repo, commitSha) {
+    return `https://github.com/${repo}/commit/${commitSha}`;
+}
+/** Human-facing copy for a phase; the branch is always named (ticket contract). */
+export function describeDeployPhase(phase, ctx) {
+    const short = ctx.commitSha.slice(0, 7);
+    const base = { commitUrl: ctx.commitUrl };
+    switch (phase) {
+        case 'committed':
+            return { ...base, tone: 'progress', text: `Committed to ${ctx.branch} · checking deploy status…` };
+        case 'building':
+            return {
+                ...base,
+                tone: 'progress',
+                text: `Committed to ${ctx.branch} · building… (usually ~1–2 min)`
+            };
+        case 'live':
+            return { ...base, tone: 'success', text: `Live on ${ctx.branch} · commit ${short}` };
+        case 'failed':
+            return { ...base, tone: 'error', text: `Build failed on ${ctx.branch} · commit ${short}` };
+        case 'unknown':
+            return {
+                ...base,
+                tone: 'progress',
+                text: `Committed to ${ctx.branch} · commit ${short} (no deploy status reported)`
+            };
+        case 'timeout':
+            return {
+                ...base,
+                tone: 'progress',
+                text: `Committed to ${ctx.branch} · status unknown (still building?) · commit ${short}`
+            };
+    }
+}
+export const defaultSchedule = (fn, ms) => {
+    const id = setTimeout(fn, ms);
+    return () => clearTimeout(id);
+};
+/**
+ * Poll `check` until a terminal status or the timeout. Emits `committed`
+ * synchronously, then a phase per poll. Stops on any terminal phase, on
+ * timeout, or on `cancel()`. Never throws — a failed check retries until the
+ * deadline.
+ */
+export function startDeployPolling(opts) {
+    const timings = opts.timings ?? DEFAULT_DEPLOY_STATUS_TIMINGS;
+    const schedule = opts.schedule ?? defaultSchedule;
+    let stopped = false;
+    let cancelNext = null;
+    let cancelDeadline = null;
+    const stop = () => {
+        stopped = true;
+        cancelNext?.();
+        cancelDeadline?.();
+        cancelNext = null;
+        cancelDeadline = null;
+    };
+    const emit = (phase, done) => {
+        if (stopped)
+            return;
+        opts.onPhase(phase);
+        if (done)
+            stop();
+    };
+    const poll = async () => {
+        if (stopped)
+            return;
+        let status;
+        try {
+            status = await opts.check();
+        }
+        catch {
+            // Transient poll failure: keep trying until the deadline fires.
+            if (!stopped)
+                cancelNext = schedule(() => void poll(), timings.intervalMs);
+            return;
+        }
+        if (stopped)
+            return;
+        const { phase, done } = deployPhaseForStatus(status);
+        emit(phase, done);
+        if (!stopped)
+            cancelNext = schedule(() => void poll(), timings.intervalMs);
+    };
+    // The commit landed; announce it before the first poll.
+    opts.onPhase('committed');
+    cancelDeadline = schedule(() => emit('timeout', true), timings.timeoutMs);
+    cancelNext = schedule(() => void poll(), timings.firstDelayMs);
+    return { cancel: stop };
+}

package/dist/document.d.ts

@@ -0,0 +1,6 @@
+import type { BlockDefinition, BlockRegistry, ContentDocument, ContentSchema } from 'uncial/core';
+export type Blocks = BlockRegistry | BlockDefinition[];
+/** Load boundary: raw forge file content → normalized Uncial document. */
+export declare function parseDocument(raw: string, blocks: Blocks, schema: ContentSchema): ContentDocument;
+/** Save boundary: validate, normalize, and serialize the document for commit. */
+export declare function serializeDocument(document: ContentDocument, blocks: Blocks, schema: ContentSchema): string;

package/dist/document.js

@@ -0,0 +1,23 @@
+import { normalizeDocument, validateDocument } from 'uncial/core';
+/** Load boundary: raw forge file content → normalized Uncial document. */
+export function parseDocument(raw, blocks, schema) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('The document file is not valid JSON.');
+    }
+    return normalizeDocument(parsed, blocks, schema);
+}
+/** Save boundary: validate, normalize, and serialize the document for commit. */
+export function serializeDocument(document, blocks, schema) {
+    const result = validateDocument(document, blocks, schema);
+    const errors = result.issues.filter((issue) => issue.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`The document failed validation and was not saved: ${errors
+            .map((issue) => issue.message)
+            .join('; ')}`);
+    }
+    return `${JSON.stringify(normalizeDocument(document, blocks, schema), null, '\t')}\n`;
+}

package/dist/editor-controller.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Headless editor-page orchestration (ticket 05). Owns the load → edit → save
+ * lifecycle, deploy-status polling, and conflict recovery, talking to the DOM
+ * only through the {@link EditorPageUi} callback surface. `mount.ts` is the DOM
+ * binding; both the per-page editor variants and the index fallback editor go
+ * through it, so all three surfaces share this one behaviour.
+ */
+import type { BlockRegistry, ContentDocument, ContentSchema } from 'uncial/core';
+import { type DeployStatusTimings, type Schedule } from './deploy-status.js';
+import type { ForgeAdapter, SessionProvider, UncialCmsSiteConfig } from './types.js';
+export interface StatusView {
+    text: string;
+    /** Optional commit permalink, rendered as a follow-up link. */
+    href?: string;
+    tone: 'progress' | 'success' | 'error';
+}
+export interface DownloadPayload {
+    filename: string;
+    content: string;
+    mimeType: string;
+}
+/** The DOM-facing surface the controller drives. */
+export interface EditorPageUi {
+    /** Render the status line (optionally with a commit link). */
+    status(view: StatusView): void;
+    /** Replace the editor's document (initial load and reload-latest). */
+    setDocument(doc: ContentDocument): void;
+    /** Enable or disable the save control. */
+    saveEnabled(enabled: boolean): void;
+    /** Show or hide the conflict recovery banner. */
+    conflictVisible(visible: boolean): void;
+}
+export interface EditorControllerOptions {
+    config: UncialCmsSiteConfig;
+    sourcePath: string;
+    /** Site-relative path for the deterministic commit message; defaults to sourcePath. */
+    pagePath?: string;
+    blocks: BlockRegistry;
+    schema: ContentSchema;
+    adapter: ForgeAdapter;
+    sessionProvider: SessionProvider;
+    ui: EditorPageUi;
+    /** Blocking confirm; the DOM binding passes `window.confirm`. */
+    confirm: (message: string) => boolean;
+    /** Trigger a file download of the given payload. */
+    download: (payload: DownloadPayload) => void;
+    timings?: DeployStatusTimings;
+    /**
+     * Debounced autosave: every change schedules a save this many milliseconds
+     * later, and a further change restarts the wait. Omitted leaves saving
+     * manual. A backend with no second writer — the local filesystem — is what
+     * this is for; on a forge every keystroke would become a commit.
+     */
+    autosaveMs?: number;
+    schedule?: Schedule;
+    /** True once the owning surface has been torn down. */
+    isDestroyed?: () => boolean;
+}
+export interface EditorController {
+    load(): Promise<void>;
+    save(): Promise<void>;
+    /** Conflict banner action (b): discard the unsaved doc and refetch (after confirm). */
+    reloadLatest(): Promise<void>;
+    /** Conflict banner action (a): download the unsaved doc as JSON. */
+    downloadMyVersion(): void;
+    /** Close the banner, leaving content and the save button untouched. */
+    dismissConflict(): void;
+    /** Forwarded editor change events. */
+    documentChanged(doc: ContentDocument): void;
+    isDirty(): boolean;
+    /** Cancel any pending autosave and any in-flight deploy polling. */
+    stop(): void;
+}
+/** Basename of the JSON source, used for the conflict download filename. */
+export declare function conflictDownloadFilename(sourcePath: string): string;
+export declare function createEditorController(opts: EditorControllerOptions): EditorController;

package/dist/editor-controller.js

@@ -0,0 +1,172 @@
+import { parseDocument, serializeDocument } from './document.js';
+import { ConflictError } from './errors.js';
+import { DEFAULT_DEPLOY_STATUS_TIMINGS, defaultSchedule, describeDeployPhase, githubCommitUrl, startDeployPolling } from './deploy-status.js';
+import { setActiveForge } from './upload-context.js';
+/** Basename of the JSON source, used for the conflict download filename. */
+export function conflictDownloadFilename(sourcePath) {
+    const base = sourcePath.split('/').pop() || 'document';
+    return base.endsWith('.json') ? base : `${base}.json`;
+}
+export function createEditorController(opts) {
+    const { config, sourcePath, blocks, schema, adapter, sessionProvider, ui } = opts;
+    const timings = opts.timings ?? DEFAULT_DEPLOY_STATUS_TIMINGS;
+    const schedule = opts.schedule ?? defaultSchedule;
+    const destroyed = () => opts.isDestroyed?.() ?? false;
+    const branch = config.forge === 'github' ? config.branch : 'the local checkout';
+    let session = null;
+    let sha = null;
+    let currentDocument = null;
+    let dirty = false;
+    let poll = null;
+    let cancelAutosave = null;
+    let saving = false;
+    let saveAgain = false;
+    const editingStatus = () => ui.status({ tone: 'progress', text: `Editing ${sourcePath} as ${session?.user.login ?? '…'}` });
+    const stopPolling = () => {
+        poll?.cancel();
+        poll = null;
+    };
+    const cancelPendingAutosave = () => {
+        cancelAutosave?.();
+        cancelAutosave = null;
+    };
+    const startPolling = (commitSha) => {
+        const commitUrl = config.forge === 'github' ? githubCommitUrl(config.repo, commitSha) : '';
+        poll = startDeployPolling({
+            check: () => adapter.commitStatus(commitSha),
+            onPhase: (phase) => {
+                if (destroyed())
+                    return;
+                const view = describeDeployPhase(phase, { branch, commitSha, commitUrl });
+                ui.status({ text: view.text, href: view.commitUrl, tone: view.tone });
+            },
+            timings,
+            schedule: opts.schedule
+        });
+    };
+    const load = async () => {
+        ui.status({ tone: 'progress', text: 'Signing in…' });
+        session = await adapter.authenticate(config, sessionProvider);
+        if (destroyed())
+            return;
+        // Publish the authenticated forge so in-editor block UIs (the Image block's
+        // upload) can reach the same adapter + author. Cleared by mountEditorPage on
+        // teardown.
+        setActiveForge({
+            adapter,
+            author: { name: session.user.name, email: session.user.email },
+            config
+        });
+        ui.status({ tone: 'progress', text: 'Loading…' });
+        const file = await adapter.readFile(sourcePath);
+        if (destroyed())
+            return;
+        sha = file.sha;
+        currentDocument = parseDocument(file.content, blocks, schema);
+        ui.setDocument(currentDocument);
+        dirty = false;
+        ui.saveEnabled(true);
+        editingStatus();
+    };
+    const save = async () => {
+        if (!session || !currentDocument)
+            return;
+        // Autosave makes overlapping writes reachable in a way manual saving did
+        // not: a keystroke landing mid-write would otherwise PUT against a sha the
+        // in-flight save is about to replace. Coalesce into one follow-up save.
+        if (saving) {
+            saveAgain = true;
+            return;
+        }
+        saving = true;
+        cancelPendingAutosave();
+        stopPolling();
+        ui.conflictVisible(false);
+        ui.saveEnabled(false);
+        ui.status({ tone: 'progress', text: 'Saving…' });
+        try {
+            const content = serializeDocument(currentDocument, blocks, schema);
+            const result = await adapter.writeFile(sourcePath, content, {
+                message: `uncial-cms: edit ${opts.pagePath ?? sourcePath}`,
+                sha: sha ?? undefined,
+                author: { name: session.user.name, email: session.user.email }
+            });
+            sha = result.sha;
+            dirty = false;
+            startPolling(result.commitSha);
+        }
+        catch (error) {
+            if (error instanceof ConflictError) {
+                // Do NOT touch content or dirty state: the unsaved edit must survive.
+                ui.conflictVisible(true);
+                ui.status({
+                    tone: 'error',
+                    text: `Save conflicted — this page changed on ${branch} since you loaded it.`
+                });
+            }
+            else {
+                ui.status({ tone: 'error', text: error instanceof Error ? error.message : 'Save failed.' });
+            }
+        }
+        finally {
+            saving = false;
+            if (!destroyed())
+                ui.saveEnabled(true);
+            if (saveAgain && !destroyed()) {
+                saveAgain = false;
+                void save();
+            }
+        }
+    };
+    const reloadLatest = async () => {
+        const proceed = opts.confirm(`Reload the latest version from ${branch}? This discards your unsaved changes` +
+            ' unless you have downloaded them.');
+        if (!proceed)
+            return; // Only "Reload latest" (confirmed) replaces content + sha.
+        const file = await adapter.readFile(sourcePath);
+        if (destroyed())
+            return;
+        sha = file.sha;
+        currentDocument = parseDocument(file.content, blocks, schema);
+        ui.setDocument(currentDocument);
+        dirty = false;
+        ui.conflictVisible(false);
+        editingStatus();
+    };
+    const downloadMyVersion = () => {
+        if (!currentDocument)
+            return;
+        opts.download({
+            filename: conflictDownloadFilename(sourcePath),
+            content: serializeDocument(currentDocument, blocks, schema),
+            mimeType: 'application/json'
+        });
+    };
+    const dismissConflict = () => {
+        ui.conflictVisible(false);
+    };
+    const documentChanged = (doc) => {
+        currentDocument = doc;
+        dirty = true;
+        if (opts.autosaveMs === undefined)
+            return;
+        cancelPendingAutosave();
+        cancelAutosave = schedule(() => {
+            cancelAutosave = null;
+            void save();
+        }, opts.autosaveMs);
+    };
+    return {
+        load,
+        save,
+        reloadLatest,
+        downloadMyVersion,
+        dismissConflict,
+        documentChanged,
+        isDirty: () => dirty,
+        stop: () => {
+            cancelPendingAutosave();
+            stopPolling();
+        }
+    };
+}

package/dist/editor-session.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The CMS's editing session without a DOM: storage, autosave, deploy status and
+ * conflict recovery, driven by a host that renders the editor however it likes.
+ *
+ * `mountEditorPage` is the other door onto the same machinery, and it builds the
+ * whole surface itself — a custom element with a shadow root, seeded with the
+ * host page's stylesheets. That is the right shape for a host with no component
+ * model to speak of. It is the wrong shape for one that has Uncial's own
+ * `Editor` component available: the shadow boundary that buys style isolation
+ * costs a framework host every rule the page sets on `body`, which is where most
+ * sites put their type and their ground.
+ *
+ * So this is the same batteries, minus the surface. A Svelte, React or Vue host
+ * renders `Editor` itself, in its own tree and its own cascade, and hands the
+ * session four callbacks and each edit as it happens.
+ *
+ * Reach it at `uncial-cms/session` rather than through the package root. The
+ * root exports `mountEditorPage` too, and importing that pulls in the custom
+ * element, its shadow-root machinery and the editor's chrome stylesheet — which
+ * a host rendering its own surface neither wants loaded nor wants arriving after
+ * its own corrections to that stylesheet.
+ */
+import { type EditorController, type EditorPageUi } from './editor-controller.js';
+import type { BlockRegistry, ContentSchema } from 'uncial/core';
+import type { ForgeAdapter, SessionProvider, UncialCmsSiteConfig } from './types.js';
+export type { DownloadPayload, EditorController, EditorPageUi, StatusView } from './editor-controller.js';
+export interface CreateEditorSessionOptions {
+    config: UncialCmsSiteConfig;
+    /** Repo-root-relative path of the JSON document being edited. */
+    sourcePath: string;
+    /**
+     * Site-relative page path, used in the deterministic commit message
+     * `uncial-cms: edit <path>`. Falls back to `sourcePath`.
+     */
+    pagePath?: string;
+    blocks: BlockRegistry;
+    schema: ContentSchema;
+    /** The four things the session needs the host to do to its own surface. */
+    ui: EditorPageUi;
+    /**
+     * Debounced autosave in milliseconds. Omitted keeps saving manual, which is
+     * what a forge backend wants — there, every keystroke would be a commit.
+     */
+    autosaveMs?: number;
+    /** Defaults to the provider the configured forge implies. */
+    sessionProvider?: SessionProvider;
+    /** Defaults to `window.confirm`. */
+    confirm?: (message: string) => boolean;
+    /** Defaults to an anchor-driven blob download. */
+    download?: (payload: {
+        filename: string;
+        content: string;
+        mimeType: string;
+    }) => void;
+    /** True once the host's surface has been torn down. */
+    isDestroyed?: () => boolean;
+}
+export declare function forgeAdapter(config: UncialCmsSiteConfig): ForgeAdapter;
+export declare function defaultSessionProvider(config: UncialCmsSiteConfig): SessionProvider;
+export declare function createEditorSession(opts: CreateEditorSessionOptions): EditorController;

package/dist/editor-session.js

@@ -0,0 +1,63 @@
+/**
+ * The CMS's editing session without a DOM: storage, autosave, deploy status and
+ * conflict recovery, driven by a host that renders the editor however it likes.
+ *
+ * `mountEditorPage` is the other door onto the same machinery, and it builds the
+ * whole surface itself — a custom element with a shadow root, seeded with the
+ * host page's stylesheets. That is the right shape for a host with no component
+ * model to speak of. It is the wrong shape for one that has Uncial's own
+ * `Editor` component available: the shadow boundary that buys style isolation
+ * costs a framework host every rule the page sets on `body`, which is where most
+ * sites put their type and their ground.
+ *
+ * So this is the same batteries, minus the surface. A Svelte, React or Vue host
+ * renders `Editor` itself, in its own tree and its own cascade, and hands the
+ * session four callbacks and each edit as it happens.
+ *
+ * Reach it at `uncial-cms/session` rather than through the package root. The
+ * root exports `mountEditorPage` too, and importing that pulls in the custom
+ * element, its shadow-root machinery and the editor's chrome stylesheet — which
+ * a host rendering its own surface neither wants loaded nor wants arriving after
+ * its own corrections to that stylesheet.
+ */
+import { createEditorController } from './editor-controller.js';
+import { createGitHubAdapter, popupSessionProvider } from './github/index.js';
+import { createLocalAdapter } from './local/adapter.js';
+import { localSessionProvider } from './local/session.js';
+export function forgeAdapter(config) {
+    if (config.forge === 'github')
+        return createGitHubAdapter();
+    if (config.forge === 'local')
+        return createLocalAdapter();
+    throw new Error(`Unknown forge "${config.forge}".`);
+}
+export function defaultSessionProvider(config) {
+    return config.forge === 'local' ? localSessionProvider : popupSessionProvider;
+}
+function triggerDownload(payload) {
+    const blob = new Blob([payload.content], { type: payload.mimeType });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = payload.filename;
+    document.body.append(anchor);
+    anchor.click();
+    anchor.remove();
+    URL.revokeObjectURL(url);
+}
+export function createEditorSession(opts) {
+    return createEditorController({
+        config: opts.config,
+        sourcePath: opts.sourcePath,
+        pagePath: opts.pagePath,
+        blocks: opts.blocks,
+        schema: opts.schema,
+        adapter: forgeAdapter(opts.config),
+        sessionProvider: opts.sessionProvider ?? defaultSessionProvider(opts.config),
+        ui: opts.ui,
+        confirm: opts.confirm ?? ((message) => window.confirm(message)),
+        download: opts.download ?? triggerDownload,
+        autosaveMs: opts.autosaveMs,
+        isDestroyed: opts.isDestroyed
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/** Thrown ONLY when a write is rejected because the provided sha is stale. */
+export declare class ConflictError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when a forge read targets a path that does not exist (404). */
+export declare class NotFoundError extends Error {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+/** Thrown ONLY when a write is rejected because the provided sha is stale. */
+export class ConflictError extends Error {
+    constructor(message = 'The document changed on the server since it was loaded.') {
+        super(message);
+        this.name = 'ConflictError';
+    }
+}
+/** Thrown when a forge read targets a path that does not exist (404). */
+export class NotFoundError extends Error {
+    constructor(message = 'The requested file does not exist.') {
+        super(message);
+        this.name = 'NotFoundError';
+    }
+}

package/dist/fit-image.d.ts

@@ -0,0 +1,31 @@
+import type { UploadAssetFile } from './index-actions.js';
+export interface EncodableImage {
+    width: number;
+    height: number;
+    close?: () => void;
+}
+/** Decode/encode seam, injected so the descent is testable without a canvas. */
+export interface ImageEncoder {
+    decode: (file: Blob) => Promise<EncodableImage>;
+    encode: (image: EncodableImage, width: number, height: number, quality: number) => Promise<Blob>;
+}
+export interface FitOptions {
+    /** Byte ceiling the result must come under; defaults to the Contents API cap. */
+    maxBytes?: number;
+    /** Longest-edge ceiling for the re-encoded image. */
+    maxEdge?: number;
+}
+export interface FittedImage extends UploadAssetFile {
+    width: number;
+    height: number;
+}
+/**
+ * Prepare `file` for upload under `maxBytes`. Bytes that already fit inside
+ * both ceilings pass through untouched, keeping their original filename and
+ * content type; anything else comes back as WebP named `<stem>.webp`.
+ */
+export declare function fitImage(file: Blob & {
+    name?: string;
+}, opts?: FitOptions & {
+    encoder?: ImageEncoder;
+}): Promise<FittedImage>;

package/dist/fit-image.js

@@ -0,0 +1,88 @@
+/**
+ * Re-encode an oversize image so it fits a size-capped forge. The Contents API
+ * refuses anything over ~1 MB, which a photograph off a phone always is, so the
+ * editor's upload path re-encodes to WebP within a bounded longest edge and
+ * steps quality — then dimensions — down until the bytes fit.
+ */
+import { MAX_CONTENT_BYTES } from './constants.js';
+const DEFAULT_MAX_EDGE = 2000;
+const INITIAL_QUALITY = 0.82;
+const MIN_QUALITY = 0.5;
+const QUALITY_STEP = 0.1;
+const SIZE_STEP = 0.85;
+const MIN_EDGE = 320;
+const browserEncoder = {
+    decode: (file) => createImageBitmap(file),
+    encode: async (image, width, height, quality) => {
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const context = canvas.getContext('2d');
+        if (!context)
+            throw new Error('This browser cannot prepare images for upload.');
+        context.drawImage(image, 0, 0, width, height);
+        const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/webp', quality));
+        if (!blob || blob.type !== 'image/webp') {
+            throw new Error('This browser cannot encode WebP images for upload.');
+        }
+        return blob;
+    }
+};
+function dimensionsWithin(width, height, longestEdge) {
+    const sourceEdge = Math.max(width, height);
+    if (sourceEdge <= longestEdge)
+        return [width, height];
+    const scale = longestEdge / sourceEdge;
+    return [Math.max(1, Math.round(width * scale)), Math.max(1, Math.round(height * scale))];
+}
+/**
+ * Prepare `file` for upload under `maxBytes`. Bytes that already fit inside
+ * both ceilings pass through untouched, keeping their original filename and
+ * content type; anything else comes back as WebP named `<stem>.webp`.
+ */
+export async function fitImage(file, opts = {}) {
+    const maxBytes = opts.maxBytes ?? MAX_CONTENT_BYTES;
+    const maxEdge = opts.maxEdge ?? DEFAULT_MAX_EDGE;
+    const encoder = opts.encoder ?? browserEncoder;
+    const filename = file.name || 'image';
+    const image = await encoder.decode(file);
+    try {
+        if (file.size <= maxBytes && Math.max(image.width, image.height) <= maxEdge) {
+            return {
+                bytes: new Uint8Array(await file.arrayBuffer()),
+                filename,
+                contentType: file.type || 'application/octet-stream',
+                width: image.width,
+                height: image.height
+            };
+        }
+        let [width, height] = dimensionsWithin(image.width, image.height, maxEdge);
+        let quality = INITIAL_QUALITY;
+        while (true) {
+            const blob = await encoder.encode(image, width, height, quality);
+            if (blob.size <= maxBytes) {
+                const stem = filename.replace(/\.[^.]*$/, '') || 'image';
+                return {
+                    bytes: new Uint8Array(await blob.arrayBuffer()),
+                    filename: `${stem}.webp`,
+                    contentType: 'image/webp',
+                    width,
+                    height
+                };
+            }
+            if (quality - QUALITY_STEP >= MIN_QUALITY) {
+                quality -= QUALITY_STEP;
+                continue;
+            }
+            const nextEdge = Math.floor(Math.max(width, height) * SIZE_STEP);
+            if (nextEdge < MIN_EDGE)
+                break;
+            [width, height] = dimensionsWithin(width, height, nextEdge);
+            quality = INITIAL_QUALITY;
+        }
+    }
+    finally {
+        image.close?.();
+    }
+    throw new Error(`Image "${filename}" could not be reduced below the ${maxBytes}-byte upload limit.`);
+}

package/dist/github/adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ForgeAdapter } from '../types.js';
+export declare const GITHUB_API_URL = "https://api.github.com";
+export declare function createGitHubAdapter(): ForgeAdapter;