@flyos/design-system-mocks

Shared External-App dev-seed plumbing — the mock-mode HTTP interceptor factory, a provider-registry dispatcher, the ok()/parseBody()/paged() response-envelope helpers, the esbuild build-flag parsing convention, an optional static-seed-asset base-URL indirection, and the canonical ./Mocks federation export contract the FlyOS desktop shell already delegates to (see the shell's core/mocks/handlers/external-apps.ts).

Deliberately NOT a secondary entry point of @flyos/design-system, and deliberately NOT added to any consumer's federation.config.js shared map. See "Why a separate package" below — same category of guardrail as @flyos/design-system-twin-face, for a different underlying reason.

Scope — plumbing, not data

This package ships the mechanism every External App was hand-rolling under a different name (Circles' core/mocks, Thoughts' core/offline-data). Per-module providers — the actual demo rows (trends, signals, users, tasks, …) — stay app-owned. This package has zero knowledge of any app's domain models or seed content.

Why a separate package, not a design-system secondary entry point

A first attempt shipped this as an ng-packagr secondary entry point (@flyos/design-system/mocks) specifically to avoid touching the design system's Native Federation singleton. That broke at runtime, not build time:

• @softarc/native-federation's getExternals() hands esbuild's external option the literal shared keys — for every consumer, that includes the bare string @flyos/design-system (it must be a shared singleton).
• esbuild's own external matching treats a bare package name as external for all of its subpaths too (name and name/* both match), regardless of whether the subpath is itself declared in shared.
• So the /mocks subpath got silently externalized in the built ./Mocks exposed chunk — but no shared bundle or importmap.json entry exists for that subpath. The chunk shipped a bare import … from "@flyos/design-system/mocks" with nothing to resolve it: an unresolved-module-specifier crash in a real browser, completely invisible to ng build succeeding or unit tests passing (verified against Thoughts' own federation build; the chunk had zero references to dispatchMockApi failures until this was caught by dumping the built chunk and importmap.json side by side).

A genuinely separate package name (fly-design-system-mocks) has no such prefix relationship with fly-design-system — esbuild's external match requires an exact name or name/ boundary — so it is bundled inline into the consuming chunk like any other ordinary, unshared dependency.

Consumer recipe

npm install @flyos/design-system-mocks --legacy-peer-deps

// my-app.router.ts
import { createProviderRegistry, type MockProvider } from '@flyos/design-system-mocks';
import { handleUsers } from './users/users.provider';

const providers: MockProvider[] = [handleUsers];
export const dispatchMyAppMocks = createProviderRegistry(providers, { delayMs: 120 });

// my-app.interceptor.ts
import { createMockApiInterceptor, parseMockBuildFlag } from '@flyos/design-system-mocks';
import { dispatchMyAppMocks } from './my-app.router';

export const myAppMockEnabled = parseMockBuildFlag(
  typeof FLY_MOCK_BACKEND !== 'undefined' ? FLY_MOCK_BACKEND : undefined,
);
export const myAppMockInterceptor = createMockApiInterceptor({
  enabled: myAppMockEnabled,
  apiPrefixes: ['/api/myapp/'],
  dispatch: dispatchMyAppMocks,
});

// federated-mocks.ts — the shell's fixed contract; rename at this one boundary
export { dispatchMyAppMocks as dispatchMockApi } from './my-app.router';

// federation.config.js — expose the router, do NOT add this package to `shared`
exposes: {
  './Mocks': './src/app/core/offline-data/federated-mocks.ts',
},

See src/public-api.ts for the full recipe, the FederatedMockContract type (the shell's fixed dispatchMockApi / optional setMockSeedBase shape), and createSeedBase() for apps whose providers fetch static JSON seed assets rather than inlining demo rows.