@arcote.tech/arc-files 0.7.13

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@arcote.tech/arc-files",
+  "type": "module",
+  "version": "0.7.13",
+  "private": false,
+  "description": "Generic file upload fragment for Arc framework — S3 presigned upload + provider file_id binding",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.7.13",
+    "@arcote.tech/arc-ds": "^0.7.13",
+    "@arcote.tech/platform": "^0.7.13",
+    "@aws-sdk/client-s3": "^3.658.0",
+    "@aws-sdk/s3-request-presigner": "^3.658.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0"
+  }
+}

package/src/aggregates/file.ts

@@ -0,0 +1,289 @@
+/// <reference path="../arc.d.ts" />
+import {
+  aggregate,
+  date,
+  mergeUnsafe,
+  number,
+  object,
+  string,
+  type ArcAggregateElement,
+  type ArcId,
+} from "@arcote.tech/arc";
+import type { S3Bridge } from "../s3/s3-client";
+import type { FileProviderName } from "../types";
+import type { FileTypeData } from "../file-type-builder";
+
+/**
+ * Built-in fields — wspólne dla wszystkich file types. Zero permission
+ * assumptions; identyfikatory scope (accountId, workspaceId itp.) idą do
+ * `.withMetadata()` per fileType.
+ */
+const builtInFields = {
+  name: string(),
+  mime: string(),
+  size: number(),
+  s3Bucket: string(),
+  s3Key: string(),
+  status: string(), // "pending" | "uploaded" | "failed"
+  providerFileIdsJson: string().optional(),
+  createdAt: date(),
+  uploadedAt: date().optional(),
+};
+
+/**
+ * Fabryka aggregate'u dla pojedynczego file type. Builder
+ * (`ArcFileTypeBuilder.build()`) zbiera state i woła tę funkcję.
+ *
+ *  - fields = `mergeUnsafe(builtIn, metadata)` — custom fields są w schema,
+ *    indexowalne i filtrowalne na poziomie dataStore (`where: {workspaceId}`).
+ *  - protectBy chain'owane per `data.protections` — arc-core OR-dispatch
+ *    po `token.name`.
+ *  - Built-in mutations: requestUpload, confirmUpload, markFailed,
+ *    bindProviderFileId, remove.
+ *  - Custom mutations z `data.mutations` — generuje `<name>Performed` event
+ *    + `<name>` mutation method.
+ */
+export function createFileTypeAggregate<const Data extends FileTypeData>(
+  data: Data,
+  s3: S3Bridge,
+  fileId: ArcId<any>,
+): ArcAggregateElement<Data["name"], ArcId<any>, any, any, any, any> {
+  const metadataShape = data.metadata;
+  const fullShape = mergeUnsafe(builtInFields, metadataShape);
+
+  // `requestUpload` params zawiera built-in (name, mime, size) + WSZYSTKIE
+  // custom metadata fields — consumer dostarcza je przy uploadzie (np.
+  // accountId, opcjonalnie workspaceId).
+  const requestUploadParams = mergeUnsafe(
+    {
+      _id: fileId,
+      name: string(),
+      mime: string(),
+      size: number(),
+    },
+    metadataShape,
+  );
+
+  // `fileRequested` event payload = `requestUploadParams` + s3 fields
+  // dodane przez handler.
+  const fileRequestedPayload = mergeUnsafe(
+    {
+      _id: fileId,
+      name: string(),
+      mime: string(),
+      size: number(),
+      s3Bucket: string(),
+      s3Key: string(),
+    },
+    metadataShape,
+  );
+
+  let agg = aggregate(data.name, fileId, fullShape)
+    .publicEvent(
+      "fileRequested",
+      fileRequestedPayload,
+      async (ctx, event) => {
+        const p = event.payload as any;
+        // Build row object: built-in fields + wszystkie custom metadata
+        const row: Record<string, any> = {
+          name: p.name,
+          mime: p.mime,
+          size: p.size,
+          s3Bucket: p.s3Bucket,
+          s3Key: p.s3Key,
+          status: "pending",
+          createdAt: event.createdAt,
+        };
+        for (const key of Object.keys(metadataShape)) {
+          row[key] = p[key];
+        }
+        await ctx.set(p._id, row as any);
+      },
+    )
+    .publicEvent("fileUploaded", { _id: fileId }, async (ctx, event) => {
+      await ctx.modify(event.payload._id, {
+        status: "uploaded",
+        uploadedAt: event.createdAt,
+      });
+    })
+    .publicEvent("fileFailed", { _id: fileId }, async (ctx, event) => {
+      await ctx.modify(event.payload._id, { status: "failed" });
+    })
+    .publicEvent(
+      "providerFileIdBound",
+      { _id: fileId, providerFileIdsJson: string() },
+      async (ctx, event) => {
+        await ctx.modify(event.payload._id, {
+          providerFileIdsJson: event.payload.providerFileIdsJson,
+        });
+      },
+    )
+    .publicEvent("fileRemoved", { _id: fileId }, async (ctx, event) => {
+      await ctx.remove(event.payload._id);
+    })
+
+    .mutateMethod("requestUpload", (fn) =>
+      fn
+        .withParams(requestUploadParams)
+        .withResult(
+          object({
+            uploadUrl: string(),
+            fileId: string(),
+            s3Key: string(),
+          }),
+        )
+        .handle(
+          ONLY_SERVER &&
+            (async (ctx, params) => {
+              const p = params as any;
+              // S3 path: `${aggregateName}/${fileId}/${filename}` — immutable.
+              // Identyfikatory scope (accountId/workspaceId) zostają w
+              // metadata fields, nie w path (zero copy on claim).
+              const s3Key = `${data.name}/${p._id}/${p.name}`;
+              const uploadUrl = await s3.presignUpload(s3Key, p.name && p.mime);
+
+              const payload: Record<string, any> = {
+                _id: p._id,
+                name: p.name,
+                mime: p.mime,
+                size: p.size,
+                s3Bucket: s3.bucket,
+                s3Key,
+              };
+              for (const key of Object.keys(metadataShape)) {
+                payload[key] = p[key];
+              }
+              await (ctx as any).fileRequested.emit(payload);
+
+              return {
+                uploadUrl,
+                fileId: String(p._id),
+                s3Key,
+              };
+            }),
+        ),
+    )
+
+    .mutateMethod("confirmUpload", (fn) =>
+      fn.withParams({ _id: fileId }).handle(
+        ONLY_SERVER &&
+          (async (ctx, params) => {
+            await ctx.fileUploaded.emit({ _id: params._id });
+          }),
+      ),
+    )
+
+    .mutateMethod("markFailed", (fn) =>
+      fn.withParams({ _id: fileId }).handle(
+        ONLY_SERVER &&
+          (async (ctx, params) => {
+            await ctx.fileFailed.emit({ _id: params._id });
+          }),
+      ),
+    )
+
+    .mutateMethod("bindProviderFileId", (fn) =>
+      fn
+        .withParams({
+          _id: fileId,
+          provider: string(),
+          providerFileId: string(),
+        })
+        .handle(
+          ONLY_SERVER &&
+            (async (ctx, params) => {
+              const existing = await ctx.$query.findOne({ _id: params._id });
+              if (!existing) return;
+              const current = parseProviderIds(
+                (existing as any).providerFileIdsJson,
+              );
+              if (
+                current[params.provider as FileProviderName] ===
+                params.providerFileId
+              ) {
+                return; // idempotent
+              }
+              current[params.provider as FileProviderName] =
+                params.providerFileId;
+              await ctx.providerFileIdBound.emit({
+                _id: params._id,
+                providerFileIdsJson: JSON.stringify(current),
+              });
+            }),
+        ),
+    )
+
+    .mutateMethod("remove", (fn) =>
+      fn.withParams({ _id: fileId }).handle(
+        ONLY_SERVER &&
+          (async (ctx, params) => {
+            const existing = await ctx.$query.findOne({ _id: params._id });
+            if (existing) {
+              try {
+                await s3.deleteObject((existing as any).s3Key as string);
+              } catch (err) {
+                console.warn("[arc-files] S3 deleteObject failed:", err);
+              }
+            }
+            await ctx.fileRemoved.emit({ _id: params._id });
+          }),
+      ),
+    );
+
+  // Chain protections — arc-core dispatchuje po tokenName.
+  // Cast do `any` w pętli — chain immutability w arc-core powoduje że literal
+  // tuple Events/MutateMethods rośnie z każdą iteracją, co przekracza TS limit.
+  let aggAny: any = agg;
+  for (const protection of data.protections) {
+    aggAny = aggAny.protectBy(protection.token, protection.check);
+  }
+
+  // Custom mutations z .withMutation() — każda dodaje:
+  //   - publicEvent `<name>Performed` z default handler (modify(_id, patch))
+  //   - mutateMethod `<name>` wrapping user handler z access do emitter
+  for (const mut of data.mutations) {
+    const eventName = `${mut.name}Performed`;
+    const eventPayload = { _id: fileId, ...mut.params };
+    aggAny = aggAny
+      .publicEvent(eventName, eventPayload, async (ctx: any, event: any) => {
+        const { _id, ...patch } = event.payload;
+        if (Object.keys(patch).length > 0) {
+          await ctx.modify(_id, patch);
+        }
+      })
+      .mutateMethod(mut.name, (fn: any) =>
+        fn.withParams({ _id: fileId, ...mut.params }).handle(
+          ONLY_SERVER &&
+            (async (ctx: any, params: any) => {
+              await mut.handler(ctx, params);
+            }),
+        ),
+      );
+  }
+
+  return aggAny
+    .clientQuery("getAll", (fn: any) =>
+      fn.handle(async (ctx: any) => ctx.$query.find({})),
+    )
+    .clientQuery("getById", (fn: any) =>
+      fn
+        .withParams({ _id: fileId })
+        .handle(async (ctx: any, params: any) =>
+          ctx.$query.findOne({ _id: params._id }),
+        ),
+    );
+}
+
+function parseProviderIds(
+  json: string | undefined,
+): Partial<Record<FileProviderName, string>> {
+  if (!json) return {};
+  try {
+    const parsed = JSON.parse(json);
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export type FileTypeAggregate = ReturnType<typeof createFileTypeAggregate>;

package/src/arc-files-builder.ts

@@ -0,0 +1,58 @@
+/// <reference path="./arc.d.ts" />
+import { createFileId } from "./ids/file";
+import { ArcFileTypeBuilder, type DefaultFileTypeData } from "./file-type-builder";
+import { S3Bridge } from "./s3/s3-client";
+import type { FileDownloader, S3Config } from "./types";
+
+/**
+ * Top-level builder dla arc-files. Tworzy shared `S3Bridge` + `fileId` brand
+ * dzielony przez wszystkie `fileType()` w obrębie tego buildera.
+ *
+ *   const filesBuilder = arcFiles({ name: "ndt", s3: { ... } });
+ *   const StrategyResearchFile = filesBuilder
+ *     .fileType("strategyResearchFile")
+ *     .withMetadata({ accountId, workspaceId: workspaceId.optional() })
+ *     .protectedBy(userToken,      (p) => ({ accountId: p.accountId }))
+ *     .protectedBy(workspaceToken, (p) => ({ workspaceId: p.workspaceId }))
+ *     .withMutation("claim", { workspaceId }, async (ctx, p) => {
+ *       await ctx.claimPerformed.emit({ _id: p._id, workspaceId: p.workspaceId });
+ *     })
+ *     .build();
+ *   const { fileId, s3, downloader } = filesBuilder.build();
+ */
+export function arcFiles<const Name extends string>(config: {
+  name: Name;
+  s3: S3Config;
+}) {
+  const s3 = new S3Bridge(config.s3);
+  const fileId = createFileId({ name: config.name });
+  const downloader: FileDownloader = {
+    download: (s3Key: string) => s3.downloadObject(s3Key),
+  };
+
+  return {
+    /**
+     * Rozpoczyna chain dla nowego file type. Nazwa staje się nazwą aggregate'u
+     * — np. `fileType("strategyResearchFile")` → `aggregate("strategyResearchFile", ...)`.
+     */
+    fileType<const TypeName extends string>(typeName: TypeName) {
+      return new ArcFileTypeBuilder<
+        DefaultFileTypeData & { name: TypeName }
+      >(
+        {
+          name: typeName,
+          metadata: {},
+          protections: [],
+          mutations: [],
+        } as DefaultFileTypeData & { name: TypeName },
+        s3,
+        fileId,
+      );
+    },
+
+    /** Shared resources — `fileId` brand, `s3` bridge, `downloader` dla openai adaptera. */
+    build() {
+      return { fileId, s3, downloader };
+    },
+  };
+}

package/src/arc.d.ts

@@ -0,0 +1,6 @@
+declare const BROWSER: boolean;
+declare const NOT_ON_BROWSER: boolean;
+declare const ONLY_BROWSER: boolean;
+declare const SERVER: boolean;
+declare const NOT_ON_SERVER: boolean;
+declare const ONLY_SERVER: boolean;

package/src/file-type-builder.ts

@@ -0,0 +1,153 @@
+/// <reference path="./arc.d.ts" />
+import type {
+  ArcId,
+  ArcRawShape,
+  ArcTokenAny,
+  Merge,
+} from "@arcote.tech/arc";
+import { createFileTypeAggregate } from "./aggregates/file";
+import type { S3Bridge } from "./s3/s3-client";
+
+/**
+ * Pojedyncza protection registered przez `.protectedBy()`. Aggregate
+ * chain'uje wszystkie protections — arc-core dispatchuje po `token.name`
+ * aktywnego tokena (semantyka OR po typie tokena).
+ */
+export interface FileTypeProtection {
+  token: ArcTokenAny;
+  // `params` is the decoded token payload; user-provided check returns
+  // a where-clause restriction (`{field: value}`) or `false` to deny.
+  check: (params: any) => Record<string, unknown> | false;
+}
+
+/**
+ * Custom mutation rejestrowana przez `.withMutation()`. Builder generuje
+ * dedicated event `<name>Performed` + mutation method z params. Handler
+ * dostaje typed `ctx` z auto-generated event emitter.
+ */
+export interface FileTypeMutation {
+  name: string;
+  params: ArcRawShape;
+  handler: (ctx: any, params: any) => Promise<void>;
+}
+
+/**
+ * State buildera — accumulated przez chain wywołań. Generic `<const Data>`
+ * preserved literal types (kluczowe dla `mergeUnsafe(builtIn, metadata)`
+ * i typed event payloads w `.attachFiles({File})`).
+ */
+export interface FileTypeData {
+  name: string;
+  metadata: ArcRawShape;
+  protections: FileTypeProtection[];
+  mutations: FileTypeMutation[];
+}
+
+export type DefaultFileTypeData = {
+  name: string;
+  metadata: {};
+  protections: [];
+  mutations: [];
+};
+
+/**
+ * Chainable builder dla pojedynczego file type. Wzór: `ArcFunction` w
+ * `packages/core/src/context-element/function/arc-function.ts`.
+ *
+ *   filesBuilder.fileType("strategyResearchFile")
+ *     .withMetadata({ accountId, workspaceId: workspaceId.optional() })
+ *     .protectedBy(userToken,      (p) => ({ accountId: p.accountId }))
+ *     .protectedBy(workspaceToken, (p) => ({ workspaceId: p.workspaceId }))
+ *     .withMutation("claim", { workspaceId }, async (ctx, p) => {
+ *       await ctx.claimPerformed.emit({ _id: p._id, workspaceId: p.workspaceId });
+ *     })
+ *     .build();   // → ArcAggregateElement
+ */
+export class ArcFileTypeBuilder<
+  const Data extends FileTypeData = DefaultFileTypeData,
+> {
+  readonly data: Data;
+  readonly #s3: S3Bridge;
+  readonly #fileId: ArcId<any>;
+
+  constructor(data: Data, s3: S3Bridge, fileId: ArcId<any>) {
+    this.data = data;
+    this.#s3 = s3;
+    this.#fileId = fileId;
+  }
+
+  /**
+   * Dodaje custom fields do aggregate schema. Generic `<const S extends ArcRawShape>`
+   * preserves literal types — fields są typed end-to-end w eventach/mutations/queries.
+   * Mergluje przez `mergeUnsafe(builtIn, metadata)` przy `.build()`.
+   */
+  withMetadata<const S extends ArcRawShape>(shape: S) {
+    return new ArcFileTypeBuilder<Merge<Data, { metadata: S }>>(
+      { ...this.data, metadata: shape } as any,
+      this.#s3,
+      this.#fileId,
+    );
+  }
+
+  /**
+   * Chain protection. Arc-core robi dispatch po `token.name` aktywnego
+   * tokena z `authAdapter.getDecoded().tokenName` — semantyka OR po typie
+   * tokena. Każdy `.protectedBy()` dodaje jeden entry do listy; przy
+   * `.build()` builder iteruje i woła `aggregate.protectBy()` per entry.
+   */
+  protectedBy<T extends ArcTokenAny>(
+    token: T,
+    check: (params: any) => Record<string, unknown> | false,
+  ) {
+    type NewProtections = [
+      ...Data["protections"],
+      { token: T; check: typeof check },
+    ];
+    return new ArcFileTypeBuilder<Merge<Data, { protections: NewProtections }>>(
+      {
+        ...this.data,
+        protections: [...this.data.protections, { token, check }],
+      } as any,
+      this.#s3,
+      this.#fileId,
+    );
+  }
+
+  /**
+   * Dodaje custom mutation z dedicated event `<name>Performed`. Handler
+   * dostaje `ctx` z auto-generated emitter dostępnym jako `ctx.<name>Performed.emit(...)`.
+   *
+   * Builder generuje:
+   *  - publicEvent `<name>Performed` z payload = `{_id, ...params}`
+   *    (default handler robi `ctx.modify(_id, patch)` — consumer może
+   *    nadpisać przez emitting custom payload)
+   *  - mutateMethod `<name>` z params = `{_id, ...params}` (ONLY_SERVER)
+   */
+  withMutation<const N extends string, const P extends ArcRawShape>(
+    name: N,
+    params: P,
+    handler: (ctx: any, params: any) => Promise<void>,
+  ) {
+    type NewMutations = [
+      ...Data["mutations"],
+      { name: N; params: P; handler: typeof handler },
+    ];
+    return new ArcFileTypeBuilder<Merge<Data, { mutations: NewMutations }>>(
+      {
+        ...this.data,
+        mutations: [...this.data.mutations, { name, params, handler }],
+      } as any,
+      this.#s3,
+      this.#fileId,
+    );
+  }
+
+  /**
+   * Finalizuje builder — zwraca konkretny `ArcAggregateElement` (z arc-core),
+   * gotowy do `context([...])` registration i do użycia w `.attachFiles({File})`,
+   * `ctx.query(File)`, `ctx.mutate(File)`.
+   */
+  build() {
+    return createFileTypeAggregate(this.data, this.#s3, this.#fileId);
+  }
+}

package/src/ids/file.ts

@@ -0,0 +1,13 @@
+import { id } from "@arcote.tech/arc";
+
+export type FileIdData = {
+  name: string;
+};
+
+export const createFileId = <const Data extends FileIdData>(
+  data: Readonly<Data>,
+) => id(`${data.name}Id`);
+
+export type FileId<Data extends FileIdData = FileIdData> = ReturnType<
+  typeof createFileId<Data>
+>;

package/src/index.ts

@@ -0,0 +1,39 @@
+// --- Builder API ---
+export { arcFiles } from "./arc-files-builder";
+
+// --- FileType builder ---
+export { ArcFileTypeBuilder } from "./file-type-builder";
+export type {
+  FileTypeData,
+  FileTypeProtection,
+  FileTypeMutation,
+  DefaultFileTypeData,
+} from "./file-type-builder";
+
+// --- Aggregate factory & type ---
+export { createFileTypeAggregate } from "./aggregates/file";
+export type { FileTypeAggregate } from "./aggregates/file";
+
+// --- ID factory & type ---
+export { createFileId } from "./ids/file";
+export type { FileId, FileIdData } from "./ids/file";
+
+// --- Types (shared with arc-ai adapters) ---
+export type {
+  ArcFileRef,
+  BoundProviderFile,
+  FileDownloader,
+  FileProviderName,
+  S3Config,
+} from "./types";
+
+// --- S3 utility (escape hatch — consumers normalnie używają `arcFiles().s3`) ---
+export { S3Bridge } from "./s3/s3-client";
+
+// --- React picker ---
+export { ArcFilePicker } from "./react/file-picker";
+export type {
+  ArcFilePickerItem,
+  ArcFilePickerMutations,
+  ArcFilePickerProps,
+} from "./react/file-picker";

package/src/react/file-picker.tsx

@@ -0,0 +1,314 @@
+import { Trans } from "@arcote.tech/platform";
+import { Button } from "@arcote.tech/arc-ds";
+import {
+  AlertCircle,
+  CheckCircle2,
+  FileText,
+  Loader2,
+  Paperclip,
+  X,
+} from "lucide-react";
+import { useRef, useState, type ReactNode } from "react";
+
+/**
+ * Reprezentacja jednego pliku w listingu (pochodzi z `ArcFile` aggregate).
+ */
+export interface ArcFilePickerItem {
+  fileId: string;
+  name: string;
+  size: number;
+  mime?: string;
+  status: "pending" | "uploaded" | "failed";
+}
+
+/**
+ * Mutations API które picker musi dostać z consumera (już zbindowane do
+ * skonkretyzowanego `File` aggregate'u w scope'ie).
+ */
+export interface ArcFilePickerMutations {
+  requestUpload: (params: {
+    name: string;
+    mime: string;
+    size: number;
+  }) => Promise<{ uploadUrl: string; fileId: string; s3Key: string }>;
+  confirmUpload: (params: { fileId: string }) => Promise<void>;
+  markFailed: (params: { fileId: string }) => Promise<void>;
+  remove: (params: { fileId: string }) => Promise<void>;
+}
+
+export interface ArcFilePickerProps {
+  /** Reactive list of files (z `useQuery().<file>.getAll()` w consumerze) */
+  files: ArcFilePickerItem[];
+  /** Zbindowane mutations do tej scope'y */
+  mutations: ArcFilePickerMutations;
+  /** Akceptowane MIME (default: PDF/DOCX/MD/TXT/CSV) */
+  acceptedMime?: string;
+  /** Max size per file w bajtach (default 10 MB) */
+  maxBytes?: number;
+  /** Max ilość plików (default 5) */
+  maxFiles?: number;
+  /** Label sekcji (default "Pliki kontekstowe") */
+  label?: ReactNode;
+  /** Hint pod listą (default opisuje akceptowane formaty + limity) */
+  hint?: ReactNode;
+  /** Pozwala na wiele plików w jednym wyborze (default true) */
+  multiple?: boolean;
+}
+
+// Akceptacja przez file dialog — mix mime + extensions. Niektóre browsery
+// zwracają nieintuicyjne `file.type` (np. CSV z Excelem → `application/vnd.ms-excel`,
+// MD bez OS mapping → ""). Lista rozszerzeń jako fallback łapie te przypadki
+// bo browser dopasowuje **albo** mime **albo** extension.
+const DEFAULT_ACCEPTED =
+  [
+    // MIME types
+    "application/pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/msword",
+    "application/vnd.ms-excel",
+    "text/markdown",
+    "text/plain",
+    "text/csv",
+    // Extensions (fallback gdy browser nie daje znanego mime)
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".md",
+    ".markdown",
+    ".txt",
+    ".csv",
+  ].join(",");
+
+/**
+ * Generyczny dropzone/picker plików dla arc-files. Consumer dostarcza
+ * `files` (z reactive query) i `mutations` (z scope'd model). Picker tylko
+ * orchestruje UX: walidacja limitów, PUT do S3, callback do markFailed.
+ */
+export function ArcFilePicker({
+  files,
+  mutations,
+  acceptedMime = DEFAULT_ACCEPTED,
+  maxBytes = 10 * 1024 * 1024,
+  maxFiles = 5,
+  label,
+  hint,
+  multiple = true,
+}: ArcFilePickerProps) {
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const atCapacity = files.length >= maxFiles;
+  const maxMB = Math.round(maxBytes / (1024 * 1024));
+
+  const handleFiles = async (fileList: FileList | null) => {
+    if (!fileList || fileList.length === 0) return;
+    setError(null);
+
+    const accepted: File[] = [];
+    for (const file of Array.from(fileList)) {
+      if (files.length + accepted.length >= maxFiles) {
+        setError(`Maksymalnie ${maxFiles} plików — pomijam resztę.`);
+        break;
+      }
+      if (file.size > maxBytes) {
+        setError(`Plik ${file.name} jest większy niż ${maxMB} MB — pomijam.`);
+        continue;
+      }
+      accepted.push(file);
+    }
+
+    if (accepted.length === 0) return;
+    setUploading(true);
+    try {
+      for (const file of accepted) {
+        // Browser czasem zwraca nieintuicyjne MIME (np. CSV z Excelem →
+        // `application/vnd.ms-excel`, MD → "", PDF z drag terminal → "").
+        // Sniff z extension jest **bardziej wiarygodny** — używamy go zawsze
+        // gdy zwraca znany typ, fallback do `file.type` tylko gdy extension
+        // nieznane. OpenAI Files API odrzuca generic mime dla `purpose=user_data`.
+        const sniffed = inferMimeFromName(file.name);
+        const mime =
+          sniffed !== "application/octet-stream"
+            ? sniffed
+            : file.type || "application/octet-stream";
+        const { uploadUrl, fileId } = await mutations.requestUpload({
+          name: file.name,
+          mime,
+          size: file.size,
+        });
+        try {
+          const putResp = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: { "Content-Type": mime },
+            body: file,
+          });
+          if (!putResp.ok) {
+            await mutations.markFailed({ fileId });
+            throw new Error(
+              `Upload failed for ${file.name}: HTTP ${putResp.status}`,
+            );
+          }
+          await mutations.confirmUpload({ fileId });
+        } catch (err) {
+          await mutations.markFailed({ fileId }).catch(() => {});
+          throw err;
+        }
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setUploading(false);
+      if (inputRef.current) inputRef.current.value = "";
+    }
+  };
+
+  const handleRemove = async (fileId: string) => {
+    await mutations.remove({ fileId });
+  };
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between">
+        <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+          {label ?? <Trans>Pliki</Trans>}{" "}
+          <span className="text-muted-foreground/60 normal-case">
+            ({files.length}/{maxFiles})
+          </span>
+        </p>
+        <Button
+          icon={Paperclip}
+          variant="ghost"
+          size="sm"
+          label={<Trans>Dodaj plik</Trans>}
+          disabled={atCapacity || uploading}
+          onClick={() => inputRef.current?.click()}
+        />
+        <input
+          ref={inputRef}
+          type="file"
+          multiple={multiple}
+          accept={acceptedMime}
+          className="hidden"
+          onChange={(e) => handleFiles(e.target.files)}
+        />
+      </div>
+
+      {hint && <p className="text-xs text-muted-foreground">{hint}</p>}
+
+      {files.length > 0 && (
+        <div className="flex flex-col gap-2">
+          {files.map((f) => (
+            <FileRow
+              key={f.fileId}
+              file={f}
+              onRemove={() => handleRemove(f.fileId)}
+            />
+          ))}
+        </div>
+      )}
+
+      {uploading && (
+        <p className="text-xs text-muted-foreground flex items-center gap-2">
+          <Loader2 className="h-3 w-3 animate-spin" />
+          <Trans>Wysyłam plik...</Trans>
+        </p>
+      )}
+
+      {error && (
+        <div className="rounded-lg border border-destructive/40 bg-destructive/5 p-2 text-xs text-destructive flex items-start gap-2">
+          <AlertCircle className="h-3.5 w-3.5 shrink-0 mt-0.5" />
+          <span>{error}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function FileRow({
+  file,
+  onRemove,
+}: {
+  file: ArcFilePickerItem;
+  onRemove: () => void;
+}) {
+  const sizeKB = file.size > 0 ? Math.round(file.size / 1024) : 0;
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-border/60 bg-background/50 px-3 py-2">
+      <FileText className="h-4 w-4 text-muted-foreground shrink-0" />
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium truncate">{file.name}</p>
+        <p className="text-xs text-muted-foreground flex items-center gap-1.5">
+          {sizeKB > 0 && <span>{sizeKB} KB</span>}
+          <StatusBadge status={file.status} />
+        </p>
+      </div>
+      <button
+        type="button"
+        onClick={onRemove}
+        className="rounded-full p-1.5 hover:bg-destructive/10 text-muted-foreground hover:text-destructive transition-colors"
+        aria-label="Usuń plik"
+      >
+        <X className="h-3.5 w-3.5" />
+      </button>
+    </div>
+  );
+}
+
+function StatusBadge({ status }: { status: "pending" | "uploaded" | "failed" }) {
+  switch (status) {
+    case "pending":
+      return (
+        <span className="inline-flex items-center gap-1 text-muted-foreground">
+          <Loader2 className="h-3 w-3 animate-spin" />
+          <Trans>Wysyłanie...</Trans>
+        </span>
+      );
+    case "uploaded":
+      return (
+        <span className="inline-flex items-center gap-1 text-green-600">
+          <CheckCircle2 className="h-3 w-3" />
+          <Trans>Gotowe</Trans>
+        </span>
+      );
+    case "failed":
+      return (
+        <span className="inline-flex items-center gap-1 text-destructive">
+          <AlertCircle className="h-3 w-3" />
+          <Trans>Błąd</Trans>
+        </span>
+      );
+  }
+}
+
+/**
+ * Sniffuje MIME z file extension. Browser czasem zwraca pusty `file.type`
+ * (np. drag z terminala, system bez extension mappings) — OpenAI Files API
+ * wymaga znanego mime dla `purpose=user_data`. Lista pokrywa typy
+ * akceptowane przez nasz default `ACCEPTED_MIME` (PDF/DOCX/MD/TXT/CSV).
+ */
+function inferMimeFromName(name: string): string {
+  const ext = name.toLowerCase().split(".").pop() ?? "";
+  switch (ext) {
+    case "pdf":
+      return "application/pdf";
+    case "docx":
+      return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    case "doc":
+      return "application/msword";
+    case "md":
+    case "markdown":
+      return "text/markdown";
+    case "txt":
+      return "text/plain";
+    case "csv":
+      return "text/csv";
+    case "json":
+      return "application/json";
+    case "html":
+    case "htm":
+      return "text/html";
+    default:
+      return "application/octet-stream";
+  }
+}

package/src/s3/s3-client.ts

@@ -0,0 +1,118 @@
+/// <reference path="../arc.d.ts" />
+import type { S3Config } from "../types";
+
+/**
+ * Server-side S3 client wrapper z **lazy aws-sdk import**.
+ *
+ * `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` to ~10 MB minified.
+ * Włączane do bundle przez statyczny import inflate'owały każdy consumer
+ * package (content.js: 340 MB, strategy.js: 84 MB, files.js: 41 MB).
+ *
+ * Po refactor: aws-sdk importowane przez `await import(...)` przy pierwszym
+ * S3 call. Konstruktor tylko zapamiętuje config (zero cost). Tree-shake
+ * bundlera wyrzuca aws-sdk z main chunks → server startup nie czeka na
+ * parsing 10 MB SDK. Pierwsze użycie ma ~100-200 ms overhead lazy load
+ * (acceptable dla async S3 operation).
+ *
+ * Cały moduł guard'owany przez `ONLY_SERVER` — w browser bundle bundler
+ * tree-shake'uje konstruktor (nigdy nie istnieje), więc browser nie widzi
+ * aws-sdk w ogóle.
+ */
+export class S3Bridge {
+  readonly bucket: string;
+  readonly #config: S3Config;
+  #clientPromise: Promise<S3ClientLike> | null = null;
+
+  constructor(config: S3Config) {
+    this.bucket = config.bucket;
+    this.#config = config;
+  }
+
+  /**
+   * Lazy client construction. Pierwszy call odpala dynamic import aws-sdk
+   * + `new S3Client(...)`; kolejne calle reużywają cached Promise.
+   */
+  async #client(): Promise<S3ClientLike> {
+    if (!ONLY_SERVER) {
+      throw new Error("S3Bridge not available in browser context");
+    }
+    if (!this.#clientPromise) {
+      this.#clientPromise = (async () => {
+        const { S3Client } = await import("@aws-sdk/client-s3");
+        return new S3Client({
+          region: this.#config.region,
+          endpoint: this.#config.endpoint,
+          credentials: {
+            accessKeyId: this.#config.accessKeyId,
+            secretAccessKey: this.#config.secretAccessKey,
+          },
+          forcePathStyle:
+            this.#config.forcePathStyle ?? Boolean(this.#config.endpoint),
+        }) as S3ClientLike;
+      })();
+    }
+    return this.#clientPromise;
+  }
+
+  async presignUpload(key: string, mime: string, expiresIn = 300) {
+    const [client, { PutObjectCommand }, { getSignedUrl }] = await Promise.all([
+      this.#client(),
+      import("@aws-sdk/client-s3"),
+      import("@aws-sdk/s3-request-presigner"),
+    ]);
+    return getSignedUrl(
+      client as any,
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        ContentType: mime,
+      }),
+      { expiresIn },
+    );
+  }
+
+  async presignDownload(key: string, expiresIn = 3600) {
+    const [client, { GetObjectCommand }, { getSignedUrl }] = await Promise.all([
+      this.#client(),
+      import("@aws-sdk/client-s3"),
+      import("@aws-sdk/s3-request-presigner"),
+    ]);
+    return getSignedUrl(
+      client as any,
+      new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+      { expiresIn },
+    );
+  }
+
+  async downloadObject(key: string): Promise<Buffer> {
+    const [client, { GetObjectCommand }] = await Promise.all([
+      this.#client(),
+      import("@aws-sdk/client-s3"),
+    ]);
+    const out = await client.send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+    );
+    const body = out.Body;
+    if (!body) throw new Error(`Empty S3 body for key: ${key}`);
+    const bytes = await (body as any).transformToByteArray();
+    return Buffer.from(bytes);
+  }
+
+  async deleteObject(key: string): Promise<void> {
+    const [client, { DeleteObjectCommand }] = await Promise.all([
+      this.#client(),
+      import("@aws-sdk/client-s3"),
+    ]);
+    await client.send(
+      new DeleteObjectCommand({ Bucket: this.bucket, Key: key }),
+    );
+  }
+}
+
+/**
+ * Minimalny interfejs `S3Client.send()` którego potrzebujemy. Unika
+ * importu typu z aws-sdk na poziomie public API (tree-shake friendly).
+ */
+interface S3ClientLike {
+  send(command: any): Promise<any>;
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Provider name for file_id binding (OpenAI / Claude / Gemini).
+ */
+export type FileProviderName = "openai" | "claude" | "gemini";
+
+/**
+ * Reference do pliku przekazywanego do LLM providera.
+ *
+ * Powstaje z `ArcFile` record + lazy uzupełnianego `providerFileIds`.
+ * Adapter providera czyta `providerFileIds[<name>]` — jeśli puste, robi
+ * lazy upload (przez wstrzyknięty `FileDownloader`) i zwraca binding w
+ * `CompletionResult.boundProviderFiles[]`. Consumer (ai-generation-listener)
+ * iteruje boundy i woła `File.bindProviderFileId(...)` per scope.
+ */
+export type ArcFileRef = {
+  fileId: string;
+  name: string;
+  mime: string;
+  s3Key: string;
+  providerFileIds?: Partial<Record<FileProviderName, string>>;
+};
+
+/**
+ * Pojedyncze binding wynikłe z lazy upload — adapter zwraca tablicę
+ * w `CompletionResult.boundProviderFiles`.
+ */
+export type BoundProviderFile = {
+  fileId: string;
+  provider: FileProviderName;
+  providerFileId: string;
+};
+
+/**
+ * Minimalny S3 utility wstrzykiwany w adapter providera. Adapter używa go
+ * do `download(s3Key) → Buffer`. Adapter nie zna aggregate'u — nie ma
+ * dependency na arc-files w arc-ai.
+ */
+export interface FileDownloader {
+  download(s3Key: string): Promise<Buffer>;
+}
+
+/**
+ * S3 config dla fragmentu — przekazywany w `arcFiles({s3: ...})`.
+ * `endpoint` opcjonalny (MinIO / R2 / inne S3-compatible).
+ */
+export type S3Config = {
+  bucket: string;
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint?: string;
+  forcePathStyle?: boolean;
+};

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["src/**/*"]
+}