fimo 0.6.0 → 0.7.0-experimental.2

package/dist/runtime/content/client/internal.js

@@ -0,0 +1,236 @@
+import { pascalCase } from 'change-case';
+// @ts-ignore - virtual module provided by fimoConfigPlugin in fimo/vite
+import fimoConfig from 'virtual:fimo-config';
+import { FimoBoolean, FimoMedia, FimoRichText, FimoString } from '../../primitives/lib/primitives.js';
+export function interpretSchema(schema) {
+    if (!schema || typeof schema.uid !== 'string' || schema.uid.length === 0) {
+        throw new Error('Content schema is missing a "uid".');
+    }
+    return {
+        uid: schema.uid,
+        pascal: pascalCase(schema.uid),
+        localized: schema.i18n?.enabled !== false,
+        isSingleton: schema.isSingleton ?? false,
+        // Codegen tolerates malformed field values (null, arrays, primitives) by
+        // treating them as untyped passthrough fields — mirror that.
+        fields: Object.entries(schema.fields ?? {}).map(([key, value]) => [key, value && typeof value === 'object' && !Array.isArray(value) ? value : {}]),
+    };
+}
+// Codegen treats an empty or non-string-bearing `targets` array as absent and
+// falls back to the monomorphic `target` — mirror that normalization so the
+// polymorphic/fixed decision, validation, and the singleton locale rule agree.
+function polymorphicTargetUids(field) {
+    if (!Array.isArray(field.targets)) {
+        return undefined;
+    }
+    const targets = field.targets.filter((uid) => typeof uid === 'string');
+    return targets.length > 0 ? targets : undefined;
+}
+export function referenceTargetUids(field) {
+    return polymorphicTargetUids(field) ?? (field.target ? [field.target] : []);
+}
+export function validateReferences(info, references) {
+    for (const [key, field] of info.fields) {
+        if (field.type !== 'reference') {
+            continue;
+        }
+        for (const uid of referenceTargetUids(field)) {
+            if (uid !== info.uid && !(uid in references)) {
+                throw new Error(`Schema "${info.uid}" field "${key}" references "${uid}", but "${uid}" is missing from the client's references map.`);
+            }
+        }
+    }
+}
+export function apiBase() {
+    // @ts-ignore - import.meta.env is a Vite feature, replaced at build time for both client and SSR
+    return import.meta.env.VITE_API_URL;
+}
+export function defaultLocale() {
+    return fimoConfig.i18n?.defaultLocale ?? 'en';
+}
+export function fimoHeaders(extra) {
+    const h = { ...extra };
+    // @ts-ignore - import.meta.env is a Vite feature
+    const branch = import.meta.env.VITE_FIMO_BRANCH;
+    if (branch) {
+        h['X-Fimo-Branch'] = branch;
+    }
+    return h;
+}
+function populateFields(populate) {
+    if (populate == null) {
+        return [];
+    }
+    return typeof populate === 'string' ? [populate] : [...populate];
+}
+export function readCollectionLocale(options, fallbackLocale = defaultLocale()) {
+    return options.locale ?? fallbackLocale;
+}
+export function readSingletonLocale(options, ownerUsesLocale, localizedReferenceFields, fallbackLocale = defaultLocale()) {
+    const populatesLocalizedTarget = populateFields(options.populate).some((field) => localizedReferenceFields.has(field));
+    return ownerUsesLocale || populatesLocalizedTarget ? (options.locale ?? fallbackLocale) : undefined;
+}
+export function buildReadPath(url, locale, populate, localeFallbacks) {
+    const u = new URL(url, 'http://fimo.local');
+    if (locale) {
+        u.searchParams.set('locale', locale);
+    }
+    if (populate != null) {
+        u.searchParams.set('populate', typeof populate === 'string' ? populate : populate.join(','));
+    }
+    if (localeFallbacks) {
+        u.searchParams.set('localeFallbacks', 'true');
+    }
+    return `${u.pathname}${u.search}`;
+}
+export function splitWritePayload(payload) {
+    const { id, entryId, documentId, locale, createdAt, updatedAt, ...data } = payload;
+    delete data.__fimo;
+    void id;
+    void entryId;
+    void createdAt;
+    void updatedAt;
+    return {
+        data,
+        ...(typeof locale === 'string' && locale.length > 0 ? { locale } : {}),
+        ...(typeof documentId === 'string' && documentId.length > 0 ? { documentId } : {}),
+    };
+}
+export function withMutationLocale(payload, activeLocale) {
+    const locale = payload.locale;
+    return { ...payload, locale: locale ?? activeLocale };
+}
+function isPopulatedEntry(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const entry = value;
+    const fimo = entry.__fimo;
+    return (typeof entry.id === 'string' &&
+        fimo != null &&
+        typeof fimo === 'object' &&
+        typeof fimo.contentType === 'string');
+}
+function asClientHandle(candidate) {
+    if (candidate == null || typeof candidate !== 'object') {
+        return undefined;
+    }
+    const handle = candidate;
+    return typeof handle.wrapWithSource === 'function' ? handle : undefined;
+}
+/**
+ * A reference is either a client or a module namespace whose default export
+ * is the client. Only ever called at request time — unwrapping a namespace's
+ * `default` mid-cycle would read an uninitialized binding. A namespace can
+ * plausibly carry BOTH a re-exported wrapWithSource and a default client, so
+ * prefer whichever shape carries meta — the locale rules depend on it.
+ */
+export function resolveClientHandle(ref) {
+    if (ref == null) {
+        return undefined;
+    }
+    const direct = asClientHandle(ref);
+    const viaDefault = asClientHandle(ref.default);
+    if (viaDefault?.meta) {
+        return viaDefault;
+    }
+    if (direct?.meta) {
+        return direct;
+    }
+    return direct ?? viaDefault;
+}
+function unresolvableReference(uid) {
+    // The template's equivalent was a compile-time import error; degrading to
+    // silently unwrapped values would kill inline editing invisibly instead.
+    return new Error(`Cannot wrap populated reference to "${uid}": its module did not resolve to a content client.`);
+}
+/**
+ * Populated polymorphic entries carry their type marker; the wrapper picks
+ * the right per-type wrapping and stamps a top-level $type so the generated
+ * union narrows in a switch. Raw (unpopulated) values and types outside the
+ * field's declared targets pass through untouched.
+ */
+function wrapPolymorphic(value, targetUids, resolve) {
+    if (!isPopulatedEntry(value)) {
+        return value;
+    }
+    const contentType = typeof value.__fimo.contentType === 'string' ? value.__fimo.contentType : null;
+    if (!contentType || !targetUids.includes(contentType)) {
+        return value;
+    }
+    const target = resolve(contentType);
+    if (!target) {
+        throw unresolvableReference(contentType);
+    }
+    const wrapped = target.wrapWithSource(value);
+    wrapped.$type = contentType;
+    return wrapped;
+}
+function wrapReference(value, uid, resolve) {
+    if (!isPopulatedEntry(value)) {
+        return value;
+    }
+    const target = resolve(uid);
+    if (!target) {
+        throw unresolvableReference(uid);
+    }
+    return target.wrapWithSource(value);
+}
+function wrapField(field, value, source, resolve) {
+    switch (field.type) {
+        case 'string':
+            return value != null ? new FimoString(value, source) : value;
+        case 'richtext':
+            return value != null ? new FimoRichText(value, source) : value;
+        case 'boolean':
+            return value != null ? new FimoBoolean(value, source) : value;
+        case 'media':
+            if (field.multiple) {
+                return (value?.map((m, i) => new FimoMedia(m, `${source}[${i}]`)) ?? value);
+            }
+            return value != null ? new FimoMedia(value, source) : value;
+        case 'reference': {
+            const polymorphic = polymorphicTargetUids(field);
+            if (polymorphic) {
+                if (field.many) {
+                    return Array.isArray(value) ? value.map((item) => wrapPolymorphic(item, polymorphic, resolve)) : value;
+                }
+                return wrapPolymorphic(value, polymorphic, resolve);
+            }
+            const uid = field.target;
+            if (!uid) {
+                return value;
+            }
+            if (field.many) {
+                return Array.isArray(value) ? value.map((item) => wrapReference(item, uid, resolve)) : value;
+            }
+            return wrapReference(value, uid, resolve);
+        }
+        default:
+            return value;
+    }
+}
+export function wrapEntry(info, entry, options) {
+    const id = entry.id;
+    const entryId = entry.entryId;
+    const documentId = entry.documentId ?? id;
+    const locale = entry.locale ?? defaultLocale();
+    const sourcePrefix = `${info.pascal}.id:${id}:${encodeURIComponent(locale)}`;
+    const entryFimo = entry.__fimo && typeof entry.__fimo === 'object' ? entry.__fimo : {};
+    const wrapped = {
+        id,
+        entryId,
+        documentId,
+        slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
+        ...(options.alwaysIncludeLocale || entry.locale ? { locale } : {}),
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+        __fimo: {
+            contentType: typeof entryFimo.contentType === 'string' ? entryFimo.contentType : info.uid,
+        },
+    };
+    for (const [key, field] of info.fields) {
+        wrapped[key] = wrapField(field, entry[key], `${sourcePrefix}.${key}`, options.resolve);
+    }
+    return wrapped;
+}

package/dist/runtime/content/client/types.d.ts

@@ -0,0 +1,136 @@
+import type { InfiniteData, UseInfiniteQueryResult, UseMutationResult, UseQueryResult, UseSuspenseQueryResult } from '@tanstack/react-query';
+import type { Fields, Populate, PopulatedResult, ProjectedWithPopulate, Query } from '../../primitives/lib/query.js';
+/**
+ * Result shape of a read: the entity with populated references applied and
+ * field projection narrowed — the runtime equivalent of the generated
+ * `{Uid}Result` alias.
+ */
+export type ContentResult<T extends {
+    id: string;
+}, TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined> = ProjectedWithPopulate<PopulatedResult<T, TPopulate> & {
+    id: string;
+}, TFields, TPopulate>;
+/**
+ * The schema definition as written in `src/schemas/<uid>.json`. The factory
+ * interprets it directly — the schema is the descriptor, so generated code
+ * never transcribes field shapes into a second format that could drift.
+ */
+export interface ContentSchemaField {
+    type?: string;
+    required?: boolean;
+    /** Media fields: multiple assets. */
+    multiple?: boolean;
+    /** Reference fields: to-many. */
+    many?: boolean;
+    /** Reference fields: target schema uid (may be this schema's own uid). */
+    target?: string;
+    /** Polymorphic reference fields: allowed target schema uids. */
+    targets?: readonly string[];
+}
+export interface ContentSchema {
+    uid: string;
+    name?: string;
+    isSingleton?: boolean;
+    i18n?: {
+        enabled?: boolean;
+    };
+    fields?: Readonly<Record<string, ContentSchemaField>>;
+}
+export interface ContentModuleMeta {
+    readonly uid: string;
+    readonly pascal: string;
+    readonly localized: boolean;
+}
+export interface ContentClientHandle {
+    wrapWithSource: (entry: Record<string, any>) => unknown;
+    meta: ContentModuleMeta;
+}
+/**
+ * A cross-referenced generated module — either a client directly, or a module
+ * namespace whose default export is the client. Generated modules for schemas
+ * that reference each other form ESM cycles, so the factory only reads
+ * properties off a ref lazily at request time, never while the client is
+ * being constructed — a namespace import is safe to pass here even mid-cycle.
+ */
+export type ContentModuleRef = ContentClientHandle | {
+    default: ContentClientHandle;
+};
+export interface ContentClientConfig {
+    schema: ContentSchema;
+    /**
+     * Every OTHER schema module this schema references, keyed by uid —
+     * `references: { Author, Video }` with namespace imports. Self-references
+     * resolve internally and never appear here.
+     */
+    references?: Readonly<Record<string, ContentModuleRef>>;
+}
+export interface ContentReadOptions<TPopulate> {
+    locale?: string;
+    populate?: TPopulate;
+    localeFallbacks?: boolean;
+}
+export interface CollectionPageInfo {
+    readonly limit: number;
+    readonly offset: number;
+    readonly total: number;
+    readonly hasMore: boolean;
+    readonly nextOffset: number | null;
+}
+export interface CollectionPage<TItem> {
+    readonly items: TItem[];
+    readonly pageInfo: CollectionPageInfo;
+}
+export type InfiniteListResult<TItem> = UseInfiniteQueryResult<InfiniteData<CollectionPage<TItem>>, Error> & {
+    readonly items: TItem[];
+    readonly total: number;
+    readonly hasMore: boolean;
+    readonly loadMore: () => ReturnType<UseInfiniteQueryResult<InfiniteData<CollectionPage<TItem>>, Error>['fetchNextPage']>;
+    readonly isLoadingMore: boolean;
+};
+export interface CollectionContentClient<T extends {
+    id: string;
+}, TInput> {
+    readonly meta: ContentModuleMeta;
+    wrapWithSource(entry: Record<string, any>): T;
+    getById<TPopulate extends Populate<T> | undefined = undefined>(id: string, options?: ContentReadOptions<TPopulate>): Promise<ContentResult<T, undefined, TPopulate>>;
+    getBySlug<TPopulate extends Populate<T> | undefined = undefined>(slug: string, options?: ContentReadOptions<TPopulate>): Promise<ContentResult<T, undefined, TPopulate> | null>;
+    getByField<TPopulate extends Populate<T> | undefined = undefined>(fieldName: string, value: string, options?: ContentReadOptions<TPopulate>): Promise<ContentResult<T, undefined, TPopulate> | null>;
+    list<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Query<T, TFields, TPopulate>): Promise<CollectionPage<ContentResult<T, TFields, TPopulate>>>;
+    get<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Query<T, TFields, TPopulate>): Promise<ContentResult<T, TFields, TPopulate>[]>;
+    create(payload: TInput): Promise<T>;
+    update(id: string, payload: Partial<TInput>): Promise<T>;
+    remove(id: string, options?: {
+        locale?: string;
+    }): Promise<void>;
+    useGetById<TPopulate extends Populate<T> | undefined = undefined>(id: string, options?: ContentReadOptions<TPopulate>): UseQueryResult<ContentResult<T, undefined, TPopulate>, Error>;
+    useGetBySlug<TPopulate extends Populate<T> | undefined = undefined>(slug: string, options?: ContentReadOptions<TPopulate>): UseQueryResult<ContentResult<T, undefined, TPopulate> | null, Error>;
+    useGetByField<TPopulate extends Populate<T> | undefined = undefined>(fieldName: string, value: string, options?: ContentReadOptions<TPopulate>): UseQueryResult<ContentResult<T, undefined, TPopulate> | null, Error>;
+    useGet<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Query<T, TFields, TPopulate>): UseQueryResult<ContentResult<T, TFields, TPopulate>[], Error>;
+    useList<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Query<T, TFields, TPopulate>): UseQueryResult<CollectionPage<ContentResult<T, TFields, TPopulate>>, Error>;
+    useInfiniteList<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Omit<Query<T, TFields, TPopulate>, 'offset'>): InfiniteListResult<ContentResult<T, TFields, TPopulate>>;
+    useSuspenseGetById<TPopulate extends Populate<T> | undefined = undefined>(id: string, options?: ContentReadOptions<TPopulate>): UseSuspenseQueryResult<ContentResult<T, undefined, TPopulate>, Error>;
+    useSuspenseGetBySlug<TPopulate extends Populate<T> | undefined = undefined>(slug: string, options?: ContentReadOptions<TPopulate>): UseSuspenseQueryResult<ContentResult<T, undefined, TPopulate> | null, Error>;
+    useSuspenseGetByField<TPopulate extends Populate<T> | undefined = undefined>(fieldName: string, value: string, options?: ContentReadOptions<TPopulate>): UseSuspenseQueryResult<ContentResult<T, undefined, TPopulate> | null, Error>;
+    useSuspenseGet<TFields extends Fields<T> | undefined = undefined, TPopulate extends Populate<T> | undefined = undefined>(params?: Query<T, TFields, TPopulate>): UseSuspenseQueryResult<ContentResult<T, TFields, TPopulate>[], Error>;
+    useCreate(): UseMutationResult<T, Error, TInput>;
+    useUpdate(): UseMutationResult<T, Error, {
+        id: string;
+        locale?: string;
+    } & Partial<TInput>>;
+    useRemove(): UseMutationResult<void, Error, string | {
+        id: string;
+        locale?: string;
+    }>;
+}
+export interface SingletonContentClient<T extends {
+    id: string;
+}, TInput> {
+    readonly meta: ContentModuleMeta;
+    wrapWithSource(entry: Record<string, any>): T;
+    get<TPopulate extends Populate<T> | undefined = undefined>(options?: ContentReadOptions<TPopulate>): Promise<ContentResult<T, undefined, TPopulate>>;
+    update(payload: Partial<TInput>): Promise<T>;
+    useGet<TPopulate extends Populate<T> | undefined = undefined>(options?: ContentReadOptions<TPopulate>): UseQueryResult<ContentResult<T, undefined, TPopulate>, Error>;
+    useSuspenseGet<TPopulate extends Populate<T> | undefined = undefined>(options?: ContentReadOptions<TPopulate>): UseSuspenseQueryResult<ContentResult<T, undefined, TPopulate>, Error>;
+    useUpdate(): UseMutationResult<T, Error, Partial<TInput>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/content/client/useQueryLocale.d.ts

@@ -0,0 +1,2 @@
+export declare function useQueryLocale(locale?: string): string;
+//# sourceMappingURL=useQueryLocale.d.ts.map

package/dist/runtime/content/client/useQueryLocale.js

@@ -0,0 +1,6 @@
+import { useLocale } from '../../i18n/FimoLocaleContext.js';
+import { defaultLocale } from './internal.js';
+export function useQueryLocale(locale) {
+    const activeLocale = useLocale().locale;
+    return locale ?? activeLocale ?? defaultLocale();
+}

package/dist/runtime/content/utils/retrieve-data-sources.d.ts

@@ -1,6 +1,7 @@
 type FieldData = Record<string, string>;
 interface RecordData {
     id: string;
+    locale?: string;
     data: FieldData;
     visible: boolean;
 }

package/dist/runtime/content/utils/retrieve-data-sources.js

@@ -1,3 +1,19 @@
+function parseRecordIdentity(token) {
+    if (!token.startsWith('id:')) {
+        return token.includes(':') ? null : { id: token };
+    }
+    const [format, id, encodedLocale, ...rest] = token.split(':');
+    if (format !== 'id' || !id || !encodedLocale || rest.length > 0) {
+        return null;
+    }
+    try {
+        const locale = decodeURIComponent(encodedLocale);
+        return locale ? { id, locale } : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Checks if an element is genuinely visible to the user within the viewport.
  * @param el The element to check.
@@ -38,7 +54,13 @@ export function retrieveVisibleDataSources() {
         const parts = source.split('.');
         // Expects the format "SchemaName.id.fieldName"
         if (parts.length === 3) {
-            const [schemaName, id, fieldName] = parts;
+            const [schemaName, identityToken, fieldName] = parts;
+            const identity = parseRecordIdentity(identityToken);
+            if (!identity) {
+                return;
+            }
+            const { id, locale } = identity;
+            const recordKey = JSON.stringify([id, locale ?? null]);
             // Skip __translations
             if (schemaName === '__translations') {
                 return;
@@ -48,16 +70,17 @@ export function retrieveVisibleDataSources() {
                 tempGroupedData[schemaName] = {};
             }
             // Ensure the record (by ID) exists for  this schema
-            if (!tempGroupedData[schemaName][id]) {
-                tempGroupedData[schemaName][id] = {
+            if (!tempGroupedData[schemaName][recordKey]) {
+                tempGroupedData[schemaName][recordKey] = {
                     id: id,
+                    ...(locale ? { locale } : {}),
                     data: {},
                     visible: isElementVisible(el),
                 };
             }
             // Add the field and its text content to the record
             if (el.textContent) {
-                tempGroupedData[schemaName][id].data[fieldName] = el.textContent.trim();
+                tempGroupedData[schemaName][recordKey].data[fieldName] = el.textContent.trim();
             }
         }
     });

package/dist/runtime/iframe/runtime/overlay-hmr.js

@@ -6,6 +6,9 @@
 // stays `undefined`. The inline overlay runtime (overlay-runtime.ts) exposes
 // its helpers on `window.__fimoOverlay`, which we call here.
 function api() {
+    if (typeof window === 'undefined') {
+        return undefined;
+    }
     return window.__fimoOverlay;
 }
 if (import.meta && import.meta.hot) {

package/dist/runtime/index.d.ts

@@ -8,6 +8,9 @@ export { DataSourcesProvider } from './content/DataSourcesProvider.js';
 export { RefreshContentProvider } from './content/RefreshContentProvider.js';
 export { parseCollectionResponse } from './content/parseCollectionResponse.js';
 export type { CollectionResponse } from './content/parseCollectionResponse.js';
+export { createContentClient } from './content/client/createContentClient.js';
+export { createSingletonClient } from './content/client/createSingletonClient.js';
+export type { CollectionContentClient, CollectionPage, CollectionPageInfo, ContentClientConfig, ContentClientHandle, ContentModuleMeta, ContentModuleRef, ContentReadOptions, ContentResult, ContentSchema, ContentSchemaField, InfiniteListResult, SingletonContentClient, } from './content/client/types.js';
 export { AppErrorBoundary } from './core/AppErrorBoundary.js';
 export { ViteLifecycles } from './core/ViteLifecycles.js';
 export { Pageview } from './t/Pageview.js';

package/dist/runtime/index.js

@@ -6,6 +6,8 @@ export { localizeFimoPath, resolveFimoLocale } from './i18n/locale.js';
 export { DataSourcesProvider } from './content/DataSourcesProvider.js';
 export { RefreshContentProvider } from './content/RefreshContentProvider.js';
 export { parseCollectionResponse } from './content/parseCollectionResponse.js';
+export { createContentClient } from './content/client/createContentClient.js';
+export { createSingletonClient } from './content/client/createSingletonClient.js';
 // Core
 export { AppErrorBoundary } from './core/AppErrorBoundary.js';
 export { ViteLifecycles } from './core/ViteLifecycles.js';

package/dist/runtime/primitives/lib/primitives.d.ts

@@ -9,12 +9,12 @@ export interface FimoSource {
     source: string;
 }
 export interface FimoReference {
-    documentId: string;
+    id: string;
 }
 /** Polymorphic reference value: the schema names a target set, so every value carries its own type. */
 export interface FimoPolymorphicReference {
     contentType: string;
-    documentId: string;
+    id: string;
 }
 export declare const FIMO_SOURCE: unique symbol;
 export declare const FIMO_PARTS: unique symbol;

package/dist/runtime/primitives/lib/query.d.ts

@@ -43,6 +43,7 @@ export type ManyReferenceOps = {
 export type FilterFor<T> = [T] extends [FimoString | string] ? string | StringOps : [T] extends [FimoBoolean | boolean] ? boolean | BoolOps : [T] extends [FimoDate | Date] ? string | DateOps : [T] extends [number] ? number | NumberOps : [T] extends [FimoPolymorphicReference | null] ? never : [T] extends [FimoPolymorphicReference[]] ? never : [T] extends [FimoReference | null] ? string | null | ReferenceOps : [T] extends [FimoReference[]] ? string | ManyReferenceOps : [T] extends [FimoMedia | FimoMedia[]] ? NullOnlyOps : [T] extends [FimoRichText] ? string | StringOps : NullOnlyOps;
 type BaseTopLevelWhere = {
     id?: string | StringOps;
+    entryId?: string | StringOps;
     documentId?: string | StringOps;
     slug?: string | StringOps;
     createdAt?: string | DateOps;
@@ -66,9 +67,10 @@ export type Fields<T> = Field<T> | readonly Field<T>[];
 type SelectedField<TField> = TField extends `__fimo.${string}` ? '__fimo' : TField;
 type SelectedFields<TFields> = TFields extends readonly (infer K)[] ? SelectedField<K> : SelectedField<TFields>;
 type ListItem<TValue> = TValue extends readonly (infer K)[] ? K : TValue;
+type EntryIdentityField<T> = Extract<'id' | 'entryId' | 'documentId' | 'locale', keyof T>;
 export type Projected<T extends {
     id: string;
-}, TFields extends Fields<T> | undefined> = [TFields] extends [undefined] ? T : Pick<T, Extract<'id' | SelectedFields<TFields>, keyof T>>;
+}, TFields extends Fields<T> | undefined> = [TFields] extends [undefined] ? T : Pick<T, EntryIdentityField<T> | Extract<SelectedFields<TFields>, keyof T>>;
 export declare const FIMO_REFERENCES: unique symbol;
 export interface WithReferences<TReferences> {
     readonly [FIMO_REFERENCES]?: TReferences;
@@ -79,7 +81,7 @@ export type Populate<TEntry> = ReferenceField<TEntry> | readonly ReferenceField<
 type PopulatedKeys<TEntry, TPopulate> = Extract<ListItem<TPopulate>, keyof ReferenceMap<TEntry> & keyof TEntry>;
 export type Populated<TEntry extends {
     id: string;
-}, TPopulate extends Populate<TEntry>> = Pick<TEntry, 'id'> & Omit<TEntry, PopulatedKeys<TEntry, TPopulate>> & {
+}, TPopulate extends Populate<TEntry>> = Pick<TEntry, EntryIdentityField<TEntry>> & Omit<TEntry, PopulatedKeys<TEntry, TPopulate>> & {
     [K in PopulatedKeys<TEntry, TPopulate>]: ReferenceMap<TEntry>[K];
 };
 export type PopulatedResult<TEntry extends {
@@ -89,7 +91,7 @@ export type PopulatedResult<TEntry extends {
 ] extends [undefined] ? TEntry : Populated<TEntry, NonNullable<TPopulate>>;
 export type ProjectedWithPopulate<T extends {
     id: string;
-}, TFields extends string | readonly string[] | undefined, TPopulate extends string | readonly string[] | undefined> = [TFields] extends [undefined] ? T : Pick<T, Extract<'id' | SelectedFields<TFields> | ListItem<NonNullable<TPopulate>>, keyof T>>;
+}, TFields extends string | readonly string[] | undefined, TPopulate extends string | readonly string[] | undefined> = [TFields] extends [undefined] ? T : Pick<T, EntryIdentityField<T> | Extract<SelectedFields<TFields> | ListItem<NonNullable<TPopulate>>, keyof T>>;
 export type Query<T extends {
     id: string;
 }, TFields extends Fields<T> | undefined = Fields<T> | undefined, TPopulate extends string | readonly string[] | undefined = string | readonly string[] | undefined> = {

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "fimo",
-  "version": "0.6.0",
+  "version": "0.7.0-experimental.2",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"
   },
   "files": [
     "dist/",
+    "!dist/**/*.d.ts.map",
     "assets/",
-    "scripts/",
+    "scripts/postinstall.mjs",
+    "scripts/lib/postinstall-onboarding.mjs",
     "templates/",
     "README.md",
     "release.json"
@@ -47,7 +49,7 @@
   "scripts": {
     "build": "pnpm run clean && tsc -b tsconfig.json && chmod +x dist/cli/index.js",
     "build:bundle": "node scripts/bundle-cli.mjs",
-    "check:types": "tsc -b tsconfig.json",
+    "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json",
     "start": "tsx src/cli/index.ts",
     "install-cli": "pnpm build && node scripts/install-cli.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
@@ -60,23 +62,16 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@clack/core": "^1.2.0",
-    "@clack/prompts": "^1.2.0",
     "@rollup/pluginutils": "^5.1.0",
-    "agent-install": "^0.0.5",
-    "better-auth": "1.4.18",
     "change-case": "^5.4.4",
-    "cheerio": "^1.0.0",
-    "commander": "^13.1.0",
     "eta": "^3.5.0",
-    "lucide-react": "^0.577.0",
-    "open": "^10.1.2",
     "oxc-parser": "^0.118.0",
     "react-error-boundary": "^6.0.0",
-    "yaml": "2.8.2",
     "zod": "4.1.8"
   },
   "devDependencies": {
+    "@clack/core": "^1.2.0",
+    "@clack/prompts": "^1.2.0",
     "@fimo/agents-bundle": "workspace:*",
     "@fimo/api-contracts": "workspace:*",
     "@fimo/cli-kit": "workspace:*",
@@ -85,7 +80,12 @@
     "@types/node": "^22.15.29",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "agent-install": "^0.0.5",
+    "better-auth": "1.4.18",
+    "cheerio": "^1.0.0",
+    "commander": "^13.1.0",
     "esbuild": "^0.25.10",
+    "open": "^10.1.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router": "^7.15.1",
@@ -93,7 +93,8 @@
     "typescript": "5.9.2",
     "vite": "^8.0.13",
     "vitest": "^4.1.6",
-    "wrangler": "^4.83.0"
+    "wrangler": "^4.83.0",
+    "yaml": "2.8.2"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.80.6",
@@ -102,6 +103,23 @@
     "react-router": "^7.0.0 || ^8.0.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20.12.0"
   }

package/release.json

@@ -1,5 +1,5 @@
 {
   "source": "npm",
-  "apiUrl": "https://api.fimo.ai",
-  "webUrl": "https://fimo.ai"
+  "apiUrl": "https://api.staging.fimo.team",
+  "webUrl": "https://staging.fimo.team"
 }

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.6.0",
+    "fimo": "0.7.0-experimental.2",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/react-router/src/pages/Index.tsx

@@ -29,7 +29,7 @@ const Index = () => {
               <a href="https://fimo.ai" target="_blank" rel="noreferrer">
                 Fimo.ai
               </a>
-              <a href="https://docs.fimo.ai" target="_blank" rel="noreferrer">
+              <a href="https://fimo.ai/docs" target="_blank" rel="noreferrer">
                 Documentation
               </a>
               <a href="https://blog.fimo.ai" target="_blank" rel="noreferrer">