fimo 2.2.0-staging.12 → 2.2.0-staging.13

package/assets/content-templates/shared/types.eta

@@ -24,6 +24,27 @@ import type { <%= referenceImport.pascal %> } from "./<%= referenceImport.pascal
 /*  ────────────  📄  Type definitions  ────────────             */
 /*───────────────────────────────────────────────────────────────*/
 
+<% if (Object.values(model.fields || {}).some(holdsMedia)) { -%>
+/**
+ * What a media field stores: a reference to a media-library asset. Point at the
+ * asset by `id`, or by the `url` an upload returned and Fimo resolves the `id`
+ * for you. `alt` belongs to the entry, so it survives replacing the asset. The
+ * facts the asset owns are never copied in, so they cannot go stale.
+ */
+export type FimoMediaRef = ({ id: string; url?: string } | { id?: string; url: string }) & {
+  alt?: string;
+  source?: "local" | "external";
+};
+
+/**
+ * What a read returns for a media field it named in `populate`: the reference
+ * plus the facts the asset owns as of that read. `name`, `mime`, `width`, and
+ * `height` remain optional when the asset is external, missing, or incomplete.
+ * A read that did not name the field returns `FimoMedia` with those facts absent.
+ */
+export type FimoPopulatedMedia = FimoMedia & { name?: string; mime?: string };
+
+<% } -%>
 /**
  * <%= model.pascal %> entity interface
  */
@@ -131,10 +152,8 @@ function getInputTypeForField(field) {
       return 'string';
     case 'json':
       return 'Record<string, unknown>';
-    case 'media': {
-      const media = 'Pick<FimoMedia, "url" | "alt" | "name" | "mime" | "width" | "height">';
-      return field.multiple ? `${media}[]` : media;
-    }
+    case 'media':
+      return field.multiple ? 'FimoMediaRef[]' : 'FimoMediaRef';
     case 'reference': {
       const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
       return field.many ? `${raw}[]` : `${raw} | null`;
@@ -176,6 +195,32 @@ function getBlocksType(field, input) {
   return `${item}[]`;
 }
 
+/** A media field, or a blocks field with a media value in some variant. */
+function holdsMedia(field) {
+  if (field.type === 'media') {
+    return true;
+  }
+  if (field.type !== 'blocks') {
+    return false;
+  }
+  const schema = field.schema || {};
+  const variants = Array.isArray(schema.oneOf) ? schema.oneOf : [schema];
+  return variants.some((variant) => Object.values(variant.fields || {}).some(holdsMedia));
+}
+
+/**
+ * What the field becomes when `populate` names it. A media field gains the
+ * asset facts; a blocks field keeps its declared item types — the media inside
+ * it is populated at runtime, but naming which variant carries which value is
+ * beyond what this flat contract can say, so the type stays conservative.
+ */
+function getPopulatedTypeForField(field) {
+  if (field.type === 'media') {
+    return field.multiple ? 'FimoPopulatedMedia[]' : 'FimoPopulatedMedia';
+  }
+  return getBlocksType(field, false);
+}
+
 function getStringLiteralUnion(field) {
   if (!Array.isArray(field.options) || field.options.length === 0) {
     return null;
@@ -202,17 +247,26 @@ function isConditionalField(field) {
   return field.showIf !== undefined || field.showIfAny !== undefined;
 }
 
-const populatedReferenceFields = Object.entries(model.fields || {}).filter(([, field]) => {
+const modelFields = Object.entries(model.fields || {});
+const populatedReferenceFields = modelFields.filter(([, field]) => {
   if (field.type !== 'reference') {
     return false;
   }
   return (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) || typeof field.targetPascal === 'string';
 });
+const populatedMediaFields = modelFields.filter(([, field]) => holdsMedia(field));
+const populatableFields = [...populatedReferenceFields, ...populatedMediaFields];
 -%>
 
-<% if (populatedReferenceFields.length === 0) { -%>
+<% if (populatableFields.length === 0) { -%>
 export type <%= model.pascal %>References = Record<never, never>;
 <% } else { -%>
+/**
+ * What each populatable field returns when a read names it in `populate`: a
+ * reference field resolves to its target entry, a media field to the asset's
+ * current facts, a blocks field to the same items with every media value
+ * inside them filled. Fields absent here are returned as stored.
+ */
 export interface <%= model.pascal %>References {
 <%
 populatedReferenceFields.forEach(([key, field]) => {
@@ -235,6 +289,11 @@ populatedReferenceFields.forEach(([key, field]) => {
   <%= key %>: <%= type %>;
 <%
 });
+populatedMediaFields.forEach(([key, field]) => {
+-%>
+  <%= key %>: <%= getPopulatedTypeForField(field) %>;
+<%
+});
 -%>
 }
 <% } -%>

package/assets/skills/fimo-code/references/assets.md

@@ -1,12 +1,12 @@
-# Assets — package surface
+# Assets in code
 
 > For the CLI commands (`fimo assets upload`, `fimo image generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
 
-This file covers the package surface for working with assets in code: the `media` field value shape, rendering primitives, and URL format.
+This file covers media fields and the Fimo image components.
 
-## `media` field value (stored/wire shape)
+## Media field values
 
-Asset values returned from `fimo assets upload` or Fimo media tasks, and stored in `media` content-type fields:
+A media field stores a reference to an asset, not a copy of the asset metadata. Write the value returned by upload or generation:
 
 ```json
 {
@@ -16,11 +16,22 @@ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored
 }
 ```
 
-- `source`: `"local"` for uploaded/generated assets in the Fimo media library. `"external"` for hard-coded third-party URLs (avoid when possible — editors can't manage these).
-- `url`: stable HTTPS URL, no auth required, safe to embed.
-- `alt`: optional alt text.
+- `source`: `"local"` for a Fimo media-library asset, or `"external"` for a third-party URL.
+- `url`: the public asset URL.
+- `alt`: optional text owned by the entry.
 
-Generated content reads wrap this stored value in `FimoMedia`, which exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height`. It does not expose `source`; Fimo tracks that internally. Pass the whole entry value to `<Image>` / `<Video>`.
+For a local asset, Fimo stores its ID and keeps the URL as a fallback. Do not copy `name`, `mime`, `width`, or `height` into the value. Those facts belong to the asset and are removed from writes.
+
+By default, reads return the stored reference without an asset lookup. Name a media or blocks field in `populate` when the page needs the asset's current URL, name, MIME type, or intrinsic size:
+
+```ts
+const post = await Post.getBySlug('hello');
+const withAsset = await Post.getBySlug('hello', { populate: ['cover'] });
+```
+
+`populate` takes top-level field names. A blocks field populates every media value inside it. One lookup covers all selected media in the response. Media inside a populated reference target stays a reference. Use `fimo assets open <id> --download` to inspect the source file.
+
+Generated reads wrap media in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass the whole value to `<Image>` or `<Video>`.
 
 ## Rendering in application code
 
@@ -41,11 +52,11 @@ import { Image, StaticImage, Video } from 'fimo-next';
 <StaticImage src="https://assets.fimo.ai/<project>/<id>.jpg" alt="Hero" width={1200} height={630} />
 ```
 
-Fimo's `<Image>` is not Next's `next/image` component. Do not pass Next-only props such as `priority`, `fill`, `quality`, or `loader`; use only the props documented for the Fimo primitive. Preserve `next/image` for non-Fimo images when the application needs those Next-specific controls.
+Fimo's `<Image>` is not Next's `next/image`. Use the Fimo props documented here. Keep `next/image` for non-Fimo images that need its controls.
 
-**Provide `width` and `height` when known** so Fimo can optimize the asset and reserve layout space (prevents CLS).
+Choose dimensions, CSS, `sizes`, and `fit` from the page design. Do not copy the source file's intrinsic dimensions into layout props by default. When a read includes intrinsic size, Fimo uses it for aspect-ratio reservation and responsive candidates.
 
-**Never hand-construct a `FimoMedia` object** to pass into `<Image>` — that bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.
+**Never hand-construct a `FimoMedia` object** to pass into `<Image>`. That bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.
 
 See `references/ui.md` for the full component table and rules.
 

package/assets/skills/fimo-code/references/content/clients.md

@@ -125,7 +125,21 @@ const page = await Article.list({
 });
 ```
 
-Fimo always keeps `id`, `entryId`, `documentId`, and `locale`. Without `populate`, references are `{ id }`; with it, they become the target entry or `null`. Populate is depth-one and only accepts reference field names.
+Fimo always keeps `id`, `entryId`, `documentId`, and `locale`, plus every field named in `populate`.
+
+`populate` is depth-one and takes top-level field names of two kinds:
+
+| Field named          | Without `populate`       | With it                                                                                     |
+| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| reference            | `{ id }`                 | the target entry, or `null`                                                                 |
+| media                | the stored reference     | `FimoPopulatedMedia` with current asset facts when it resolves; asset facts remain optional |
+| blocks holding media | stored references inside | every media value inside it populated; item types unchanged                                 |
+
+Any other field name is a 400. A populated reference target carries its own media as stored references. Population does not recurse, and a missing or external asset keeps its stored media value.
+
+Even when media is populated, `id`, `name`, `mime`, `width`, and `height` can be absent for external, missing, or incomplete assets. The stored `url` remains the fallback, and `alt` is optional entry-owned text.
+
+Generated schema modules keep `FimoMediaRef` and `FimoPopulatedMedia` local. Their shapes depend on the schema, while the installed runtime package may be an older release.
 
 When a named type is needed, use the generated result type rather than typing populated data as the base entry:
 

package/assets/skills/fimo-migration/SKILL.md

@@ -248,9 +248,13 @@ ID supplied by the owner — without one, stop with an unresolved owner action
 instead of inventing an ID:
 
 - Link an owner-supplied (empty) project:
-  `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
+  `fimo migrate init <target-dir> --project-id <projectId> --framework <framework> --source-platform <platform>`
 - Create a new project in an owner-supplied organization:
-  `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+  `fimo migrate init <target-dir> --org <organizationId> --framework <framework> --source-platform <platform>`
+
+`--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
+`astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
+`other`); pass what the source checkout proves, `unknown` only when nothing does.
 
 After setup, check `.fimo/config.json#runtime.framework` and the scaffold's
 framework files before starting workers. A Next.js target must still have its
@@ -286,7 +290,10 @@ Commands that perform actual data writes, all requiring the linked target:
 - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
 - `fimo migrate init` (source-backed form): the project link/creation and
-  initial commit push described above.
+  initial commit push described above. Pass `--source-platform <platform>`
+  (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
+  react-router, other) when the source is known; URL crawls detect it.
+
 - `fimo link`: project creation or selection plus the in-place adoption of a
   copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.

package/assets/skills/fimo-migration/references/media.md

@@ -86,6 +86,17 @@ the asset owns the uploaded bytes and their metadata, and the entry field holds
 the media value `{ source, url, alt }` that points at it. Keep both carrying the
 same alt text, and do not duplicate alt into a second schema field.
 
+Do not copy upload metadata into media values yourself. Writing `{ source, url,
+alt }` is enough: the write path resolves and persists the media-library ID, and
+a read that names the field in `populate` returns the asset's current URL, name,
+MIME type, and intrinsic dimensions from the library. A read that does not name
+it returns the stored reference. The ID lets you inspect the asset later with
+`fimo assets open <id> --download`.
+
+Treat intrinsic dimensions as source facts, not layout instructions. Choose the
+displayed size, crop, `sizes`, loading behavior, and fit from the migrated page's
+design and responsive behavior.
+
 ## Failure Handling
 
 If a media asset cannot be downloaded or uploaded:

package/assets/skills/fimo-migration/references/workflow.md

@@ -21,6 +21,9 @@ ask a generic optimization question.
    - URL migration: `fimo migrate init <source-url> <target-dir> --framework <framework>`
    - link an existing project: `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
    - create a project: `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+   - add `--source-platform <platform>` when the source platform is known
+     (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
+     react-router, other); URL crawls detect it themselves.
      Use the detected source framework for source-backed migrations. A framework
      conversion requires an explicit user choice; URL-only and rebuild
      migrations ask the user which framework to use. Never choose a framework by

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-28T14:46:45.101Z",
+  "bundledAt": "2026-08-28T21:37:20.437Z",
   "cliVersion": "2.1.0",
   "external": [
     "oxc-parser",