@wildo-ai/zod-decorators 1.1.4 → 1.1.6

package/dist/esm/zod-duration.d.ts

@@ -98,6 +98,8 @@ export type DecoratedDurationSchema = z.ZodObject<{
     unit: z.ZodTypeAny;
 }> & {
     [ZodDecorator.IS_DB_INDEXED](): DecoratedDurationSchema;
+    /** Installed at runtime with the other chainable methods; declared here so an authored `.durationUI(…)` typechecks. */
+    [ZodDecorator.DURATION_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DURATION_UI]): DecoratedDurationSchema;
     [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedDurationSchema;
     [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedDurationSchema;
     [ZodDecorator.IS_SUMMARY_FIELD](params?: SummaryFieldParams): DecoratedDurationSchema;

package/dist/esm/zod-duration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod-duration.d.ts","sourceRoot":"","sources":["../../src/zod-duration.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,cAAc,EAId,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAeD,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,2FAAkD,CAAC;AAElF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAsBrE;AAeD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,aAAa,EAChB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,MAAM,CAOR;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,uBAAuB,CAyCzB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,SAAS,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC;IACnB,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC;CACpB,CAAC,GAAG;IACH,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,uBAAuB,CAAC;IACxD,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,uBAAuB,CAAC;IAC5G,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,uBAAuB,CAAC;IACxH,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,uBAAuB,CAAC;IACtF,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,uBAAuB,CAAC;IACxH,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,oBAAoB,CAAC,GAAG,uBAAuB,CAAC;IAClI,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,uBAAuB,CAAC;IAC9D,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,uBAAuB,CAAC;IAC9D,aAAa,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,uBAAuB,CAAC;CACtE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,uBAAuB,CAEnF;AACD,oDAAoD;AAEpD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yBAGlC,CAAC"}
+{"version":3,"file":"zod-duration.d.ts","sourceRoot":"","sources":["../../../src/zod-duration.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,cAAc,EAId,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAeD,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,2FAAkD,CAAC;AAElF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAsBrE;AAeD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,aAAa,EAChB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,MAAM,CAOR;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,uBAAuB,CAyCzB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,SAAS,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC;IACnB,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC;CACpB,CAAC,GAAG;IACH,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,uBAAuB,CAAC;IACxD,uHAAuH;IACvH,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,uBAAuB,CAAC;IAChH,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,uBAAuB,CAAC;IAC5G,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,uBAAuB,CAAC;IACxH,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,uBAAuB,CAAC;IACtF,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,uBAAuB,CAAC;IACxH,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,YAAY,CAAC,oBAAoB,CAAC,GAAG,uBAAuB,CAAC;IAClI,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,uBAAuB,CAAC;IAC9D,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,uBAAuB,CAAC;IAC9D,aAAa,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,uBAAuB,CAAC;CACtE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,uBAAuB,CAEnF;AACD,oDAAoD;AAEpD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yBAGlC,CAAC"}

package/dist/esm/zod-duration.js

@@ -22,8 +22,8 @@ export const DurationUnitSchema = z.enum(DurationUnit).systemEnum('DurationUnit'
  * Zod schema for DurationValue.
  */
 export const DurationValueSchema = z.object({
-    value: z.number().int().min(0),
-    unit: DurationUnitSchema,
+    value: z.number().int().min(0).describe("How many `unit`s the duration lasts."),
+    unit: DurationUnitSchema.describe("The unit `value` is counted in."),
 });
 /**
  * Convert a duration to total seconds for canonical storage/comparison.
@@ -128,8 +128,8 @@ export function createDurationSchema(options = {}) {
         ? z.enum([allowedUnits[0], ...allowedUnits.slice(1)])
         : DurationUnitSchema;
     const durationSchema = z.object({
-        value: valueSchema,
-        unit: unitSchema,
+        value: valueSchema.describe("How many `unit`s the duration lasts."),
+        unit: unitSchema.describe("The unit `value` is counted in."),
     });
     const durationMetadata = {
         isDuration: true,

package/dist/esm/zod-duration.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod-duration.js","sourceRoot":"","sources":["../../../src/zod-duration.ts"],"names":[],"mappings":"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","sourcesContent":["\n// ============================================================================\n// DURATION SCHEMA HELPER\n// ============================================================================\n\nimport {\n  DecoratorInput,\n  SCHEMA_METADATA,\n  CustomFieldMetadata,\n  DurationSchemaMetadata,\n  DurationUnit,\n  SummaryFieldParams,\n  ZodDecorator,\n  ZodDecorator_ParamsType,\n} from './zod-decorators.types';\nimport { z } from 'zod';\nimport { addChainableMethods } from './zod.module-override';\n\n/**\n * @wildo_source:part:start zod.factories.duration facet:layer:shared facet:family:schema-factory\n *\n * Duration value type — represents a time span with value and unit.\n *\n * Stored as { value: number, unit: DurationUnit } for clarity and flexibility.\n * Use durationToSeconds() for canonical conversion when needed (e.g., TTL, expiry).\n *\n * @example\n * { value: 5, unit: DurationUnit.MINUTES }  // 5 minutes\n * { value: 1, unit: DurationUnit.HOURS }    // 1 hour\n */\nexport interface DurationValue {\n  /** Numeric quantity (must be non-negative for typical use) */\n  value: number;\n  /** Unit of time */\n  unit: DurationUnit;\n}\n\n/**\n * Options for creating a duration schema via z_duration().\n * Uses the DurationUnit enum for type-safe configuration.\n */\nexport interface DurationSchemaOptions {\n  /** Allowed units (if empty/undefined, all units are allowed) */\n  allowedUnits?: DurationUnit[];\n  /** Minimum value (for the numeric part) */\n  minValue?: number;\n  /** Maximum value (for the numeric part) */\n  maxValue?: number;\n}\n\n/** Seconds multiplier for each duration unit */\nconst DURATION_MULTIPLIERS: Record<DurationUnit, number> = {\n  [DurationUnit.MILLISECONDS]: 0.001,\n  [DurationUnit.SECONDS]: 1,\n  [DurationUnit.MINUTES]: 60,\n  [DurationUnit.HOURS]: 3600,\n  [DurationUnit.DAYS]: 86400,\n  [DurationUnit.WEEKS]: 604800,\n  [DurationUnit.MONTHS]: 30 * 86400,\n  [DurationUnit.YEARS]: 365.25 * 86400,\n  [DurationUnit.CENTURIES]: 100 * 365.25 * 86400,\n};\n\n/** Canonical Zod schema for DurationUnit. Clone via `z_clone()` for independent metadata. */\nexport const DurationUnitSchema = z.enum(DurationUnit).systemEnum('DurationUnit');\n\n/**\n * Zod schema for DurationValue.\n */\nexport const DurationValueSchema = z.object({\n  value: z.number().int().min(0),\n  unit: DurationUnitSchema,\n});\n\n/**\n * Convert a duration to total seconds for canonical storage/comparison.\n * Use when setting TTL, expiry, or comparing durations.\n *\n * @param d - Duration value\n * @returns Total seconds\n */\nexport function durationToSeconds(d: DurationValue): number {\n  return d.value * DURATION_MULTIPLIERS[d.unit];\n}\n\n/**\n * Create a duration from total seconds, using the most appropriate unit.\n * Prefers larger units when the value divides evenly.\n *\n * @param totalSeconds - Total seconds\n * @returns DurationValue\n */\nexport function secondsToDuration(totalSeconds: number): DurationValue {\n  if (totalSeconds <= 0) {\n    return { value: 0, unit: DurationUnit.SECONDS };\n  }\n  const units: DurationUnit[] = [\n    DurationUnit.CENTURIES,\n    DurationUnit.YEARS,\n    DurationUnit.MONTHS,\n    DurationUnit.WEEKS,\n    DurationUnit.DAYS,\n    DurationUnit.HOURS,\n    DurationUnit.MINUTES,\n    DurationUnit.SECONDS,\n    DurationUnit.MILLISECONDS,\n  ];\n  for (const unit of units) {\n    const m = DURATION_MULTIPLIERS[unit];\n    if (totalSeconds % m === 0 && totalSeconds >= m) {\n      return { value: totalSeconds / m, unit };\n    }\n  }\n  return { value: totalSeconds, unit: DurationUnit.SECONDS };\n}\n\n/** Singular form for each duration unit (when value is 1) */\nconst DURATION_UNIT_SINGULAR: Record<DurationUnit, string> = {\n  [DurationUnit.MILLISECONDS]: 'millisecond',\n  [DurationUnit.SECONDS]: 'second',\n  [DurationUnit.MINUTES]: 'minute',\n  [DurationUnit.HOURS]: 'hour',\n  [DurationUnit.DAYS]: 'day',\n  [DurationUnit.WEEKS]: 'week',\n  [DurationUnit.MONTHS]: 'month',\n  [DurationUnit.YEARS]: 'year',\n  [DurationUnit.CENTURIES]: 'century',\n};\n\n/**\n * Format a duration for display.\n *\n * @param d - Duration value\n * @param options - Format options\n * @returns Formatted string (e.g., \"5 minutes\", \"1 hour\")\n */\nexport function formatDuration(\n  d: DurationValue,\n  options: { pluralize?: boolean } = {}\n): string {\n  const { pluralize = true } = options;\n  const label =\n    pluralize && d.value === 1\n      ? DURATION_UNIT_SINGULAR[d.unit] ?? d.unit\n      : d.unit;\n  return `${d.value} ${label}`;\n}\n\n/**\n * z_duration() - Creates duration schemas for time spans.\n *\n * Duration values are stored as { value, unit }.\n * Use durationToSeconds() when you need canonical seconds (e.g., TTL).\n *\n * @example\n * ```typescript\n * import { z_duration, DurationUnit } from '@wildo-ai/zod-decorators';\n *\n * const sessionTtl = z_duration();\n * const allowedUnits = z_duration({ allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS] });\n *\n * // UI props via .durationUI()\n * z_duration().durationUI({ edit: { defaultUnit: DurationUnit.MINUTES } })\n * z_duration({ allowedUnits: [DurationUnit.HOURS, DurationUnit.DAYS] }).durationUI({ edit: { defaultUnit: DurationUnit.HOURS } })\n * ```\n */\n\n/**\n * Creates a duration schema with metadata for detection and form component rendering.\n *\n * @param options - Configuration options for duration field\n * @returns A Zod object schema with metadata for duration detection\n */\nexport function createDurationSchema(\n  options: DurationSchemaOptions = {}\n): DecoratedDurationSchema {\n  const {\n    allowedUnits,\n    minValue,\n    maxValue,\n  } = options;\n\n  let valueSchema = z.number().int().min(0);\n  if (minValue !== undefined) {\n    valueSchema = valueSchema.min(minValue);\n  }\n  if (maxValue !== undefined) {\n    valueSchema = valueSchema.max(maxValue);\n  }\n\n  const unitSchema =\n    allowedUnits && allowedUnits.length > 0\n      ? z.enum([allowedUnits[0], ...allowedUnits.slice(1)] as [string, ...string[]])\n      : DurationUnitSchema;\n\n  const durationSchema = z.object({\n    value: valueSchema,\n    unit: unitSchema,\n  });\n\n  const durationMetadata: DurationSchemaMetadata = {\n    isDuration: true,\n    ...(allowedUnits && allowedUnits.length > 0 && { allowedUnits }),\n    ...(minValue !== undefined && { minValue }),\n    ...(maxValue !== undefined && { maxValue }),\n  };\n\n  const existingMetadata: CustomFieldMetadata = (durationSchema as any)[SCHEMA_METADATA] || {};\n  (durationSchema as any)[SCHEMA_METADATA] = {\n    ...existingMetadata,\n    durationConfig: durationMetadata,\n  };\n\n  addChainableMethods(durationSchema);\n\n  return durationSchema as unknown as DecoratedDurationSchema;\n}\n\n/**\n * Return type for duration schemas - includes decorator methods.\n */\nexport type DecoratedDurationSchema = z.ZodObject<{\n  value: z.ZodNumber;\n  unit: z.ZodTypeAny;\n}> & {\n  [ZodDecorator.IS_DB_INDEXED](): DecoratedDurationSchema;\n  [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedDurationSchema;\n  [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedDurationSchema;\n  [ZodDecorator.IS_SUMMARY_FIELD](params?: SummaryFieldParams): DecoratedDurationSchema;\n  [ZodDecorator.IS_BACKEND_ONLY](params?: ZodDecorator_ParamsType[ZodDecorator.IS_BACKEND_ONLY]): DecoratedDurationSchema;\n  [ZodDecorator.IS_WRITE_ONLY_SECRET](params?: ZodDecorator_ParamsType[ZodDecorator.IS_WRITE_ONLY_SECRET]): DecoratedDurationSchema;\n  [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedDurationSchema;\n  [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedDurationSchema;\n  addDecorators(decorators: DecoratorInput[]): DecoratedDurationSchema;\n};\n\n/**\n * Creates a duration schema for time spans.\n *\n * @example\n * ```typescript\n * import { z_duration, DurationUnit } from '@wildo-ai/zod-decorators';\n *\n * z_duration()\n * z_duration({ allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS, DurationUnit.DAYS] })\n * z_duration({ minValue: 1, maxValue: 1440 })  // 1–1440 minutes\n *\n * // UI props via .durationUI()\n * z_duration().durationUI({ edit: { defaultUnit: DurationUnit.HOURS } })\n * ```\n */\nexport function z_duration(options?: DurationSchemaOptions): DecoratedDurationSchema {\n  return createDurationSchema(options);\n}\n/** @wildo_source:part:end zod.factories.duration */\n\n/**\n * Schema for token expiry duration — minutes, hours, or days only, value ≥ 1.\n * Use for expiresIn in consumable tokens, sharableDefaults, and share API.\n */\nexport const ExpiresInDurationSchema = z_duration({\n  minValue: 1,\n  allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS, DurationUnit.DAYS],\n});\n"]}
+{"version":3,"file":"zod-duration.js","sourceRoot":"","sources":["../../../src/zod-duration.ts"],"names":[],"mappings":"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","sourcesContent":["\n// ============================================================================\n// DURATION SCHEMA HELPER\n// ============================================================================\n\nimport {\n  DecoratorInput,\n  SCHEMA_METADATA,\n  CustomFieldMetadata,\n  DurationSchemaMetadata,\n  DurationUnit,\n  SummaryFieldParams,\n  ZodDecorator,\n  ZodDecorator_ParamsType,\n} from './zod-decorators.types';\nimport { z } from 'zod';\nimport { addChainableMethods } from './zod.module-override';\n\n/**\n * @wildo_source:part:start zod.factories.duration facet:layer:shared facet:family:schema-factory\n *\n * Duration value type — represents a time span with value and unit.\n *\n * Stored as { value: number, unit: DurationUnit } for clarity and flexibility.\n * Use durationToSeconds() for canonical conversion when needed (e.g., TTL, expiry).\n *\n * @example\n * { value: 5, unit: DurationUnit.MINUTES }  // 5 minutes\n * { value: 1, unit: DurationUnit.HOURS }    // 1 hour\n */\nexport interface DurationValue {\n  /** Numeric quantity (must be non-negative for typical use) */\n  value: number;\n  /** Unit of time */\n  unit: DurationUnit;\n}\n\n/**\n * Options for creating a duration schema via z_duration().\n * Uses the DurationUnit enum for type-safe configuration.\n */\nexport interface DurationSchemaOptions {\n  /** Allowed units (if empty/undefined, all units are allowed) */\n  allowedUnits?: DurationUnit[];\n  /** Minimum value (for the numeric part) */\n  minValue?: number;\n  /** Maximum value (for the numeric part) */\n  maxValue?: number;\n}\n\n/** Seconds multiplier for each duration unit */\nconst DURATION_MULTIPLIERS: Record<DurationUnit, number> = {\n  [DurationUnit.MILLISECONDS]: 0.001,\n  [DurationUnit.SECONDS]: 1,\n  [DurationUnit.MINUTES]: 60,\n  [DurationUnit.HOURS]: 3600,\n  [DurationUnit.DAYS]: 86400,\n  [DurationUnit.WEEKS]: 604800,\n  [DurationUnit.MONTHS]: 30 * 86400,\n  [DurationUnit.YEARS]: 365.25 * 86400,\n  [DurationUnit.CENTURIES]: 100 * 365.25 * 86400,\n};\n\n/** Canonical Zod schema for DurationUnit. Clone via `z_clone()` for independent metadata. */\nexport const DurationUnitSchema = z.enum(DurationUnit).systemEnum('DurationUnit');\n\n/**\n * Zod schema for DurationValue.\n */\nexport const DurationValueSchema = z.object({\n  value: z.number().int().min(0).describe(\"How many `unit`s the duration lasts.\"),\n  unit: DurationUnitSchema.describe(\"The unit `value` is counted in.\"),\n});\n\n/**\n * Convert a duration to total seconds for canonical storage/comparison.\n * Use when setting TTL, expiry, or comparing durations.\n *\n * @param d - Duration value\n * @returns Total seconds\n */\nexport function durationToSeconds(d: DurationValue): number {\n  return d.value * DURATION_MULTIPLIERS[d.unit];\n}\n\n/**\n * Create a duration from total seconds, using the most appropriate unit.\n * Prefers larger units when the value divides evenly.\n *\n * @param totalSeconds - Total seconds\n * @returns DurationValue\n */\nexport function secondsToDuration(totalSeconds: number): DurationValue {\n  if (totalSeconds <= 0) {\n    return { value: 0, unit: DurationUnit.SECONDS };\n  }\n  const units: DurationUnit[] = [\n    DurationUnit.CENTURIES,\n    DurationUnit.YEARS,\n    DurationUnit.MONTHS,\n    DurationUnit.WEEKS,\n    DurationUnit.DAYS,\n    DurationUnit.HOURS,\n    DurationUnit.MINUTES,\n    DurationUnit.SECONDS,\n    DurationUnit.MILLISECONDS,\n  ];\n  for (const unit of units) {\n    const m = DURATION_MULTIPLIERS[unit];\n    if (totalSeconds % m === 0 && totalSeconds >= m) {\n      return { value: totalSeconds / m, unit };\n    }\n  }\n  return { value: totalSeconds, unit: DurationUnit.SECONDS };\n}\n\n/** Singular form for each duration unit (when value is 1) */\nconst DURATION_UNIT_SINGULAR: Record<DurationUnit, string> = {\n  [DurationUnit.MILLISECONDS]: 'millisecond',\n  [DurationUnit.SECONDS]: 'second',\n  [DurationUnit.MINUTES]: 'minute',\n  [DurationUnit.HOURS]: 'hour',\n  [DurationUnit.DAYS]: 'day',\n  [DurationUnit.WEEKS]: 'week',\n  [DurationUnit.MONTHS]: 'month',\n  [DurationUnit.YEARS]: 'year',\n  [DurationUnit.CENTURIES]: 'century',\n};\n\n/**\n * Format a duration for display.\n *\n * @param d - Duration value\n * @param options - Format options\n * @returns Formatted string (e.g., \"5 minutes\", \"1 hour\")\n */\nexport function formatDuration(\n  d: DurationValue,\n  options: { pluralize?: boolean } = {}\n): string {\n  const { pluralize = true } = options;\n  const label =\n    pluralize && d.value === 1\n      ? DURATION_UNIT_SINGULAR[d.unit] ?? d.unit\n      : d.unit;\n  return `${d.value} ${label}`;\n}\n\n/**\n * z_duration() - Creates duration schemas for time spans.\n *\n * Duration values are stored as { value, unit }.\n * Use durationToSeconds() when you need canonical seconds (e.g., TTL).\n *\n * @example\n * ```typescript\n * import { z_duration, DurationUnit } from '@wildo-ai/zod-decorators';\n *\n * const sessionTtl = z_duration();\n * const allowedUnits = z_duration({ allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS] });\n *\n * // UI props via .durationUI()\n * z_duration().durationUI({ edit: { defaultUnit: DurationUnit.MINUTES } })\n * z_duration({ allowedUnits: [DurationUnit.HOURS, DurationUnit.DAYS] }).durationUI({ edit: { defaultUnit: DurationUnit.HOURS } })\n * ```\n */\n\n/**\n * Creates a duration schema with metadata for detection and form component rendering.\n *\n * @param options - Configuration options for duration field\n * @returns A Zod object schema with metadata for duration detection\n */\nexport function createDurationSchema(\n  options: DurationSchemaOptions = {}\n): DecoratedDurationSchema {\n  const {\n    allowedUnits,\n    minValue,\n    maxValue,\n  } = options;\n\n  let valueSchema = z.number().int().min(0);\n  if (minValue !== undefined) {\n    valueSchema = valueSchema.min(minValue);\n  }\n  if (maxValue !== undefined) {\n    valueSchema = valueSchema.max(maxValue);\n  }\n\n  const unitSchema =\n    allowedUnits && allowedUnits.length > 0\n      ? z.enum([allowedUnits[0], ...allowedUnits.slice(1)] as [string, ...string[]])\n      : DurationUnitSchema;\n\n  const durationSchema = z.object({\n    value: valueSchema.describe(\"How many `unit`s the duration lasts.\"),\n    unit: unitSchema.describe(\"The unit `value` is counted in.\"),\n  });\n\n  const durationMetadata: DurationSchemaMetadata = {\n    isDuration: true,\n    ...(allowedUnits && allowedUnits.length > 0 && { allowedUnits }),\n    ...(minValue !== undefined && { minValue }),\n    ...(maxValue !== undefined && { maxValue }),\n  };\n\n  const existingMetadata: CustomFieldMetadata = (durationSchema as any)[SCHEMA_METADATA] || {};\n  (durationSchema as any)[SCHEMA_METADATA] = {\n    ...existingMetadata,\n    durationConfig: durationMetadata,\n  };\n\n  addChainableMethods(durationSchema);\n\n  return durationSchema as unknown as DecoratedDurationSchema;\n}\n\n/**\n * Return type for duration schemas - includes decorator methods.\n */\nexport type DecoratedDurationSchema = z.ZodObject<{\n  value: z.ZodNumber;\n  unit: z.ZodTypeAny;\n}> & {\n  [ZodDecorator.IS_DB_INDEXED](): DecoratedDurationSchema;\n  /** Installed at runtime with the other chainable methods; declared here so an authored `.durationUI(…)` typechecks. */\n  [ZodDecorator.DURATION_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DURATION_UI]): DecoratedDurationSchema;\n  [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedDurationSchema;\n  [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedDurationSchema;\n  [ZodDecorator.IS_SUMMARY_FIELD](params?: SummaryFieldParams): DecoratedDurationSchema;\n  [ZodDecorator.IS_BACKEND_ONLY](params?: ZodDecorator_ParamsType[ZodDecorator.IS_BACKEND_ONLY]): DecoratedDurationSchema;\n  [ZodDecorator.IS_WRITE_ONLY_SECRET](params?: ZodDecorator_ParamsType[ZodDecorator.IS_WRITE_ONLY_SECRET]): DecoratedDurationSchema;\n  [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedDurationSchema;\n  [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedDurationSchema;\n  addDecorators(decorators: DecoratorInput[]): DecoratedDurationSchema;\n};\n\n/**\n * Creates a duration schema for time spans.\n *\n * @example\n * ```typescript\n * import { z_duration, DurationUnit } from '@wildo-ai/zod-decorators';\n *\n * z_duration()\n * z_duration({ allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS, DurationUnit.DAYS] })\n * z_duration({ minValue: 1, maxValue: 1440 })  // 1–1440 minutes\n *\n * // UI props via .durationUI()\n * z_duration().durationUI({ edit: { defaultUnit: DurationUnit.HOURS } })\n * ```\n */\nexport function z_duration(options?: DurationSchemaOptions): DecoratedDurationSchema {\n  return createDurationSchema(options);\n}\n/** @wildo_source:part:end zod.factories.duration */\n\n/**\n * Schema for token expiry duration — minutes, hours, or days only, value ≥ 1.\n * Use for expiresIn in consumable tokens, sharableDefaults, and share API.\n */\nexport const ExpiresInDurationSchema = z_duration({\n  minValue: 1,\n  allowedUnits: [DurationUnit.MINUTES, DurationUnit.HOURS, DurationUnit.DAYS],\n});\n"]}

package/dist/esm/zod-file.d.ts

@@ -1,5 +1,6 @@
-import { FileSchemaOptions, FileMimeTypeGroup, FileNature, FileDisplayNature, FileDisplayPresentation, type FileActivationConfig, type FileUIDisplayParams, FileStorageAccepted, FileNatureConstraints_Image, FileNatureConstraints_Video, FileNatureConstraints_Audio, FileNatureConstraints_Document } from "./zod-decorators.types";
+import { FileSchemaOptions, FileMimeTypeGroup, FileNature, FileDisplayNature, FileDisplayPresentation, type FileActivationConfig, type FileUIDisplayParams, FileStorageAccepted, FileNatureConstraints_Image, FileNatureConstraints_Video, FileNatureConstraints_Audio, FileNatureConstraints_Document, ZodDecorator, ZodDecorator_ParamsType } from "./zod-decorators.types";
 import { z } from "zod";
+import { AgentFileFormat } from "./files/agent-file-formats";
 /**
  * Single file value type - represents a single file reference stored in the database.
  * The actual file is stored in a file storage system, this object references it.
@@ -128,6 +129,19 @@ export interface DecoratedFileSchema extends z.ZodObject<{
     fileId: z.ZodString;
     updatedAt: z.ZodDate;
 }> {
+    /**
+     * Declared here, as the sibling factories declare theirs (`DecoratedMoneySchema.moneyUI`,
+     * `DecoratedPhoneSchema.phoneUI`, …), because a file's display and edit policy is authored on
+     * the factory's output and nowhere else. The applyable-type map admits `fileUI` on `ZodObject`,
+     * but a bare `z.object({...})` is not a file, so the base prototype deliberately does not carry
+     * it — the per-instance install `createFileSchema` performs is what makes it reachable.
+     *
+     * Not a RE-declaration: `fileUI` is absent from the `ZodObject` module augmentation, so this adds
+     * a member rather than conflicting with one. That distinction is what the TS2320 note above is
+     * about — re-declaring a member the augmentation already carries is what broke here before.
+     */
+    [ZodDecorator.FILE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_UI]): DecoratedFileSchema;
+    [ZodDecorator.FILE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_SPEC]): DecoratedFileSchema;
 }
 /**
  * Return type for multiple file schemas - includes decorator methods.
@@ -139,6 +153,19 @@ export interface DecoratedMultipleFileSchema extends z.ZodObject<{
     fileIds: z.ZodArray<z.ZodString>;
     updatedAt: z.ZodDate;
 }> {
+    /**
+     * Declared here, as the sibling factories declare theirs (`DecoratedMoneySchema.moneyUI`,
+     * `DecoratedPhoneSchema.phoneUI`, …), because a file's display and edit policy is authored on
+     * the factory's output and nowhere else. The applyable-type map admits `fileUI` on `ZodObject`,
+     * but a bare `z.object({...})` is not a file, so the base prototype deliberately does not carry
+     * it — the per-instance install `createFileSchema` performs is what makes it reachable. Mirrors the single-file interface above.
+     *
+     * Not a RE-declaration: `fileUI` is absent from the `ZodObject` module augmentation, so this adds
+     * a member rather than conflicting with one. That distinction is what the TS2320 note above is
+     * about — re-declaring a member the augmentation already carries is what broke here before.
+     */
+    [ZodDecorator.FILE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_UI]): DecoratedMultipleFileSchema;
+    [ZodDecorator.FILE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_SPEC]): DecoratedMultipleFileSchema;
 }
 /**
  * Creates a file schema for file uploads with reference storage.
@@ -206,10 +233,40 @@ export declare function getFileExtension(filename: string): string;
  */
 export declare function isMimeTypeAllowed(mimeType: string, allowedMimeTypes?: string[]): boolean;
 /**
- * Get a human-readable description of allowed file types.
- * Uses UnifiedFileFormatRegistry for better format detection.
+ * How an accepted file type is identified — the discriminator of {@link AcceptedFileKind}.
  */
-export declare function getAcceptDescription(allowedMimeTypes?: string[]): string;
+export declare enum AcceptedFileKindCategory {
+    /** A broad nature (images, PDF, office documents, …) — one {@link FileNature} member. */
+    NATURE = "nature",
+    /** A text format an agent can produce — one {@link AgentFileFormat} member. */
+    AGENT_FORMAT = "agent_format",
+    /** Neither: the MIME subtype itself (`csv` for `text/csv`), shown as the value it is. */
+    MIME_SUBTYPE = "mime_subtype"
+}
+/** One kind of file a field accepts, as a FACT a renderer names — never as words. */
+export type AcceptedFileKind = {
+    category: AcceptedFileKindCategory.NATURE;
+    nature: FileNature;
+} | {
+    category: AcceptedFileKindCategory.AGENT_FORMAT;
+    format: AgentFileFormat;
+} | {
+    category: AcceptedFileKindCategory.MIME_SUBTYPE;
+    subtype: string;
+};
+/**
+ * The kinds of file a field's `allowedMimeTypes` admit, deduplicated, in first-seen order. An empty
+ * result means every file is accepted.
+ *
+ * This answers FACTS and the renderer names them from its label tree. It used to answer an English
+ * sentence ("Images, PDF, Text files") from two hand-kept maps plus a humanizing fallback — words
+ * produced by code in a package with no i18n at all, which no locale could translate (#1283,
+ * `.claude/rules/display-text-comes-from-i18n.md`).
+ *
+ * Resolution per MIME type: the unified format registry first (a nature, or an agent format), then
+ * the broad MIME families the registry does not classify, then the subtype as a value.
+ */
+export declare function getAcceptedFileKinds(allowedMimeTypes?: string[]): AcceptedFileKind[];
 /**
  * Get file nature from schema metadata.
  * @param schema - Zod schema (must be a file schema)
@@ -241,6 +298,15 @@ export declare function getFileConstraints(schema: z.ZodTypeAny): {
  * 2. `mimeType` (from file metadata or browser File object) → detected via MIME prefix matching
  * 3. `FileDisplayNature.GENERIC` (fallback)
  *
+ * `FileNature.ALL` is not a nature, it is the ABSENCE of a declaration: a field that accepts anything
+ * says nothing about the file in front of it. So it does not decide at step 1 — the file's own MIME
+ * type does, exactly as for a field with no declared nature. Until 2026-09-24 it mapped to GENERIC and
+ * won, so every file in an open field, a PNG and a PDF included, resolved to GENERIC: no preview, and
+ * an authored `OVERLAY` activation always degraded to a download. `resolveFileDisplayPolicy` already
+ * describes the intended behaviour ("the file's ACTUAL nature has no displayer — which is only
+ * reachable when the schema declared an open nature"); this is what makes that sentence true.
+ * `FileNature.ARCHIVE` stays GENERIC at step 1, because that IS a declaration.
+ *
  * @param schemaNature - The `FileNature` declared in schema metadata (from `getFileMetadata(schema)?.nature`)
  * @param mimeType - The MIME type of the actual file
  * @returns The `FileDisplayNature` to use for rendering

package/dist/esm/zod-file.d.ts.map

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

package/dist/esm/zod-file.js

@@ -5,16 +5,18 @@ import { SCHEMA_METADATA, FileMimeTypeGroups, FileNature, FileDisplayNature, Fil
 import { z } from "zod";
 import { addChainableMethods, addDecorators } from "./zod.module-override.js";
 import { UnifiedFileFormatRegistry } from "./files/unified-registry.js";
+import { AgentFileFormat } from "./files/agent-file-formats.js";
 /**
  * Deduplicated warning tracker for unsupported storage providers.
  * Prevents console spam when the same schema is created multiple times (e.g., in tests or HMR).
  */
 const _warnedStorageProviders = new Set();
 /**
- * The storages an `IFileStorageProvider` exists for. `GOOGLE_DRIVE` joined on
- * 2026-09-09 (#394 P5): its bytes stay in Drive, read and written through the
- * connected account of the person who linked or uploaded them. `ONEDRIVE` and
- * `DROPBOX` remain declared-but-unserved until each gets a provider.
+ * The storages the ENGINE serves itself. `GOOGLE_DRIVE` joined on 2026-09-09 (#394 P5): its bytes stay
+ * in Drive, read and written through the connected account of the person who linked or uploaded them.
+ * Any other member is served only when a loaded provider contributes an adapter (#1674) —
+ * `ONEDRIVE` by the engine's `microsoft-onedrive` once scoped — which this decorator package cannot see, so it
+ * warns about those members rather than refusing them.
  */
 const _supportedProviders = new Set([FileStorageAccepted.WILDO_MANAGED, FileStorageAccepted.LOCAL_DIRECTORY, FileStorageAccepted.GOOGLE_DRIVE]);
 const GENERATED_PDF_MIME_TYPES = ['application/pdf'];
@@ -23,15 +25,15 @@ const GENERATION_METADATA_KEYS = new Set(['source', 'templateId']);
  * Zod schema for SingleFileValue.
  */
 export const SingleFileValueSchema = z.object({
-    fileId: z.string().min(1),
-    updatedAt: z.date(),
+    fileId: z.string().min(1).describe("The stored file's identifier. Read the file's details from the file metadata endpoint, or from `file` when the read populates files."),
+    updatedAt: z.date().describe("When this file reference was last set."),
 });
 /**
  * Zod schema for MultipleFileValue.
  */
 export const MultipleFileValueSchema = z.object({
-    fileIds: z.array(z.string().min(1)),
-    updatedAt: z.date(),
+    fileIds: z.array(z.string().min(1)).describe("The stored files' identifiers, in order."),
+    updatedAt: z.date().describe("When this file reference was last set."),
 });
 /**
  * Resolve MIME type groups to actual MIME types.
@@ -172,16 +174,24 @@ function assertGeneratedPdfFileOptions(params) {
  */
 export function createFileSchema(options = {}) {
     const { overridable = true, allowedMimeTypes, maxSize, minSize, multiple = false, maxFiles, nature, storageAccepted, filePathBinding, generation, imageConstraints, videoConstraints, audioConstraints, documentConstraints, ragSource, textExtraction, scanPolicy, onParentDelete = 'cascade', sharable, sharableDefaults, } = options;
-    // Warn at schema creation for a storage no provider serves yet — a declared vocabulary member with no implementation
+    // Warn at schema creation for a storage the engine does not serve itself — served only if a provider package contributes it
     // Uses deduplication to avoid console spam during tests or HMR
     if (storageAccepted && storageAccepted.some(s => !_supportedProviders.has(s))) {
         const unsupported = storageAccepted.filter(s => !_supportedProviders.has(s));
         const warnKey = unsupported.sort().join(',');
         if (!_warnedStorageProviders.has(warnKey)) {
             _warnedStorageProviders.add(warnKey);
-            console.warn(`[z_file] storageAccepted contains unsupported providers: ${unsupported.join(', ')}. ` +
-                `Implemented: ${[..._supportedProviders].map((s) => `'${s}'`).join(', ')}. ` +
-                `A declared-but-unserved storage is skipped by the storage router until its provider exists.`);
+            // The two cases are NOT the same outcome, and saying only "skipped" understates the second
+            // badly enough to be misleading: alongside an implemented storage the declaration really is
+            // ignored, but as the ONLY declared storage it stops the application booting. That is the
+            // split #460 records, stated here at the moment an author writes the declaration — earlier
+            // than the startup validator and the storage router, which draw the same distinction.
+            console.warn(`[z_file] storageAccepted names storage(s) the engine does not serve itself: ${unsupported.join(', ')}. ` +
+                `The engine serves: ${[..._supportedProviders].map((s) => `'${s}'`).join(', ')}. ` +
+                `Another storage is served only when a provider the application scopes contributes an adapter for it ` +
+                `('onedrive': the engine's microsoft-onedrive provider). With none, declared ALONGSIDE a served storage it is ` +
+                `skipped by the storage router; declared as the ONLY storage the application refuses to boot and every upload ` +
+                `to this field is refused, and no environment variable enables it — a storage with no provider cannot be configured into existence.`);
         }
     }
     if (filePathBinding) {
@@ -211,12 +221,12 @@ export function createFileSchema(options = {}) {
     // Create the file object schema based on single/multiple
     const fileSchema = multiple
         ? z.object({
-            fileIds: z.array(z.string().min(1)),
-            updatedAt: z.date(),
+            fileIds: z.array(z.string().min(1)).describe("The stored files' identifiers, in order."),
+            updatedAt: z.date().describe("When this file reference was last set."),
         })
         : z.object({
-            fileId: z.string().min(1),
-            updatedAt: z.date(),
+            fileId: z.string().min(1).describe("The stored file's identifier. Read the file's details from the file metadata endpoint, or from `file` when the read populates files."),
+            updatedAt: z.date().describe("When this file reference was last set."),
         });
     // No longer stored in metadata — consumers derive accept from allowedMimeTypes via buildAcceptAttribute()
     // Store file metadata in SCHEMA_METADATA.fileConfig
@@ -392,72 +402,70 @@ export function isMimeTypeAllowed(mimeType, allowedMimeTypes) {
     return false;
 }
 /**
- * Get a human-readable description of allowed file types.
- * Uses UnifiedFileFormatRegistry for better format detection.
+ * How an accepted file type is identified — the discriminator of {@link AcceptedFileKind}.
  */
-export function getAcceptDescription(allowedMimeTypes) {
+export var AcceptedFileKindCategory;
+(function (AcceptedFileKindCategory) {
+    /** A broad nature (images, PDF, office documents, …) — one {@link FileNature} member. */
+    AcceptedFileKindCategory["NATURE"] = "nature";
+    /** A text format an agent can produce — one {@link AgentFileFormat} member. */
+    AcceptedFileKindCategory["AGENT_FORMAT"] = "agent_format";
+    /** Neither: the MIME subtype itself (`csv` for `text/csv`), shown as the value it is. */
+    AcceptedFileKindCategory["MIME_SUBTYPE"] = "mime_subtype";
+})(AcceptedFileKindCategory || (AcceptedFileKindCategory = {}));
+const AGENT_FILE_FORMAT_VALUES = new Set(Object.values(AgentFileFormat));
+/**
+ * The kinds of file a field's `allowedMimeTypes` admit, deduplicated, in first-seen order. An empty
+ * result means every file is accepted.
+ *
+ * This answers FACTS and the renderer names them from its label tree. It used to answer an English
+ * sentence ("Images, PDF, Text files") from two hand-kept maps plus a humanizing fallback — words
+ * produced by code in a package with no i18n at all, which no locale could translate (#1283,
+ * `.claude/rules/display-text-comes-from-i18n.md`).
+ *
+ * Resolution per MIME type: the unified format registry first (a nature, or an agent format), then
+ * the broad MIME families the registry does not classify, then the subtype as a value.
+ */
+export function getAcceptedFileKinds(allowedMimeTypes) {
     if (!allowedMimeTypes || allowedMimeTypes.length === 0)
-        return 'All files';
-    const types = new Set();
+        return [];
+    const kinds = [];
+    const seen = new Set();
+    const add = (kind, identity) => {
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        kinds.push(kind);
+    };
+    const addNature = (nature) => add({ category: AcceptedFileKindCategory.NATURE, nature }, `nature:${nature}`);
     for (const mime of allowedMimeTypes) {
-        // Use registry to detect format type
         const formatType = UnifiedFileFormatRegistry.getFormatTypeFromMimeType(mime);
-        if (formatType) {
-            if (formatType.type === 'nature') {
-                // Map FileNature to human-readable names
-                const natureNames = {
-                    [FileNature.IMAGE]: 'Images',
-                    [FileNature.VIDEO]: 'Videos',
-                    [FileNature.AUDIO]: 'Audio files',
-                    [FileNature.PDF]: 'PDF',
-                    [FileNature.OFFICE]: 'Office documents',
-                    [FileNature.ARCHIVE]: 'Archives',
-                };
-                const name = natureNames[formatType.nature];
-                if (name) {
-                    types.add(name);
-                    continue;
-                }
-            }
-            else if (formatType.type === 'agent') {
-                // Map agent formats to human-readable names
-                const agentNames = {
-                    'text': 'Text files',
-                    'markdown': 'Markdown',
-                    'json': 'JSON',
-                    'typescript': 'TypeScript',
-                    'typescript_react': 'TypeScript React',
-                    'yaml': 'YAML',
-                };
-                const name = agentNames[formatType.format] || formatType.format.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
-                types.add(name);
-                continue;
-            }
-        }
-        // Fallback: use MIME type patterns
-        if (mime === 'application/pdf') {
-            types.add('PDF');
-        }
-        else if (mime.startsWith('image/')) {
-            types.add('Images');
+        if (formatType?.type === 'nature') {
+            addNature(formatType.nature);
+            continue;
         }
-        else if (mime.startsWith('video/')) {
-            types.add('Videos');
-        }
-        else if (mime.startsWith('audio/')) {
-            types.add('Audio');
-        }
-        else if (mime.includes('document') || mime.includes('word') || mime.includes('excel') || mime.includes('powerpoint')) {
-            types.add('Office documents');
+        if (formatType?.type === 'agent' && AGENT_FILE_FORMAT_VALUES.has(formatType.format)) {
+            const format = formatType.format;
+            add({ category: AcceptedFileKindCategory.AGENT_FORMAT, format }, `agent:${format}`);
+            continue;
         }
+        if (mime === 'application/pdf')
+            addNature(FileNature.PDF);
+        else if (mime.startsWith('image/'))
+            addNature(FileNature.IMAGE);
+        else if (mime.startsWith('video/'))
+            addNature(FileNature.VIDEO);
+        else if (mime.startsWith('audio/'))
+            addNature(FileNature.AUDIO);
+        else if (mime.includes('document') || mime.includes('word') || mime.includes('excel') || mime.includes('powerpoint'))
+            addNature(FileNature.OFFICE);
         else {
-            // Get extension-like description
-            const ext = mime.split('/').pop()?.toUpperCase();
-            if (ext)
-                types.add(ext);
+            const subtype = mime.split('/').pop();
+            if (subtype)
+                add({ category: AcceptedFileKindCategory.MIME_SUBTYPE, subtype }, `subtype:${subtype}`);
         }
     }
-    return Array.from(types).join(', ') || 'Selected file types';
+    return kinds;
 }
 /**
  * Get file nature from schema metadata.
@@ -545,6 +553,15 @@ function detectDisplayNatureFromMimeType(mimeType) {
  * 2. `mimeType` (from file metadata or browser File object) → detected via MIME prefix matching
  * 3. `FileDisplayNature.GENERIC` (fallback)
  *
+ * `FileNature.ALL` is not a nature, it is the ABSENCE of a declaration: a field that accepts anything
+ * says nothing about the file in front of it. So it does not decide at step 1 — the file's own MIME
+ * type does, exactly as for a field with no declared nature. Until 2026-09-24 it mapped to GENERIC and
+ * won, so every file in an open field, a PNG and a PDF included, resolved to GENERIC: no preview, and
+ * an authored `OVERLAY` activation always degraded to a download. `resolveFileDisplayPolicy` already
+ * describes the intended behaviour ("the file's ACTUAL nature has no displayer — which is only
+ * reachable when the schema declared an open nature"); this is what makes that sentence true.
+ * `FileNature.ARCHIVE` stays GENERIC at step 1, because that IS a declaration.
+ *
  * @param schemaNature - The `FileNature` declared in schema metadata (from `getFileMetadata(schema)?.nature`)
  * @param mimeType - The MIME type of the actual file
  * @returns The `FileDisplayNature` to use for rendering
@@ -556,8 +573,8 @@ function detectDisplayNatureFromMimeType(mimeType) {
  * ```
  */
 export function resolveFileDisplayNature(schemaNature, mimeType) {
-    // Priority 1: Schema-declared nature
-    if (schemaNature) {
+    // Priority 1: Schema-declared nature — `ALL` declares nothing, so it falls through to the file itself.
+    if (schemaNature && schemaNature !== FileNature.ALL) {
         return FILE_NATURE_TO_DISPLAY_NATURE[schemaNature] ?? FileDisplayNature.GENERIC;
     }
     // Priority 2: MIME type detection