@astryxdesign/cli 0.3.0-canary.c857354 → 0.3.0-canary.d52d2cb

package/api/component/_adapter.mjs

@@ -270,6 +270,9 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
   let resolvedName = dirName;
   // Track the resolving owner so the detail payload can carry ownership info.
   // Defaults to core; the legacy-external fallback below may reassign it.
+  // Annotated because CORE_PACKAGE's generated declaration carries the literal
+  // type, which (unlike a fresh literal) does not widen on assignment.
+  /** @type {string} */
   let resolvedOwnerPackage = CORE_PACKAGE;
   let resolvedSourcePath = readmePath ? findComponentSource(coreDir, dirName) : null;
 

package/api/integration/validate-integration.d.mts

@@ -1,24 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * Validate an already-LOADED integration (as produced by
- * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
- * plus identity) and return its issues. This is the reuse seam for everyday
- * commands that have already loaded the configured integrations and want the
- * SAME validators that `validate-integration` runs, without re-resolving the
- * manifest from disk.
- *
- * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
- * already validated it (and throws otherwise), so by the time a command holds a
- * loaded integration the manifest is known-good. We re-run the on-disk
- * contribution checks (roots + codemods/templates/components) because those can
- * regress independently of the manifest (a deleted directory, a broken template).
- *
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
- * @returns {Promise<Issue[]>}
- */
-export function validateLoadedIntegration(loaded: import("./validate-integration.type.mjs").LoadedIntegration): Promise<Issue[]>;
 /**
  * Validate the LOCAL integration package rooted at `cwd`: nearest package.json
  * + a single sibling astryx.integration.{ts,mjs,js}. A missing manifest yields
@@ -59,6 +41,7 @@ export function summarizeIssues(issues: Issue[]): {
     errors: number;
     warnings: number;
 };
+export { validateLoadedIntegration };
 export type Issue = import("../../foundation/integrations/issue").AstryxIntegrationIssue;
 export type ValidateResult = {
     /**
@@ -79,3 +62,4 @@ export type ValidateResult = {
     manifestFile?: string | undefined;
     issues: Issue[];
 };
+import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';

package/api/integration/validate-integration.mjs

@@ -17,6 +17,14 @@
  * is false only for the no-manifest local case, which is guidance (not an
  * error) so `validate-integration` can stay exit-0 in a non-integration dir.
  *
+ * The on-disk contribution validators themselves (roots + codemods/templates/
+ * components, behind `validateLoadedIntegration`) live in
+ * `foundation/integrations/validate-contributions.mjs`, because foundation also
+ * runs them: `Project` collects integration issues and `integration-warnings`
+ * nudges about them on ordinary commands. This file re-exports
+ * `validateLoadedIntegration` so existing importers are unaffected, and keeps
+ * the command-level entry points that resolve a manifest from disk.
+ *
  * Validators are intentionally small and independent so more checks can be
  * appended without reshaping the result. Issue `code`s are stable public
  * strings.
@@ -30,9 +38,14 @@ import {
   loadManifestObject,
   resolvePackageDir,
 } from '../../foundation/integrations/integrations.mjs';
-import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
-import {discoverIntegrationTemplatesForOne} from '../template/template.mjs';
-import * as componentDiscovery from '../../foundation/discovery/component-discovery.mjs';
+// The on-disk contribution validators live in foundation: Project and
+// integration-warnings need them too, and foundation must not depend on api.
+import {
+  validateLoadedIntegration,
+  issueError as error,
+} from '../../foundation/integrations/validate-contributions.mjs';
+
+export {validateLoadedIntegration};
 
 /**
  * @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue
@@ -63,144 +76,6 @@ function findNearestPackageJson(cwd) {
   }
 }
 
-/** @param {string} code @param {string} message @returns {Issue} */
-function error(code, message) {
-  return {code, severity: 'error', message};
-}
-
-/**
- * Verify each declared contribution root exists on disk. A declared-but-missing
- * root is a `missing_root` error.
- * @param {{components?: string, templates?: string, codemods?: string}} resolved
- *   absolute resolved roots (undefined when not declared)
- * @param {Issue[]} issues
- */
-function checkRoots(resolved, issues) {
-  const kinds = /** @type {const} */ (['components', 'templates', 'codemods']);
-  for (const kind of kinds) {
-    const root = resolved[kind];
-    if (root == null) continue;
-    if (!fs.existsSync(root)) {
-      issues.push(
-        error(
-          'missing_root',
-          `Declared ${kind} root does not exist on disk: ${root}`,
-        ),
-      );
-    }
-  }
-}
-
-/**
- * Validate the integration's codemods via the landed discovery. Discovery is
- * strict (throws on bad export / duplicate id); we convert any throw into an
- * `invalid_codemod` error.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkCodemods(integration, issues) {
-  if (!integration.codemods || !fs.existsSync(integration.codemods)) return;
-  try {
-    await discoverIntegrationCodemods([integration]);
-  } catch (err) {
-    issues.push(error('invalid_codemod', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Validate the integration's templates via the landed discovery. Per-template
- * problems are reported as `invalid_template` errors.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkTemplates(integration, issues) {
-  if (!integration.templates || !fs.existsSync(integration.templates)) return;
-  try {
-    const {errors} = await discoverIntegrationTemplatesForOne(integration);
-    for (const e of errors) {
-      issues.push(error('invalid_template', e.message));
-    }
-  } catch (err) {
-    issues.push(error('invalid_template', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Validate the integration's components via the landed ownership discovery.
- * Feature-detected: if the component-ownership export isn't present in this
- * build (sibling PR not yet merged), component validation is skipped rather
- * than hard-failing.
- *
- * `discoverIntegrationComponents` returns ownership records and does not throw
- * on a missing same-stem source — it records `sourcePath: null`. We surface
- * each such record as an `invalid_component` error.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkComponents(integration, issues) {
-  if (!integration.components || !fs.existsSync(integration.components)) return;
-  const discover = componentDiscovery.discoverIntegrationComponents;
-  if (typeof discover !== 'function') return; // feature not present yet
-  try {
-    const records = (await discover(integration)) ?? [];
-    for (const record of records) {
-      if (record?.sourcePath == null) {
-        issues.push(
-          error(
-            'invalid_component',
-            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx.`,
-          ),
-        );
-      }
-    }
-  } catch (err) {
-    issues.push(error('invalid_component', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Run every contribution validator against a loaded-integration-shaped object.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration
- * @param {Issue[]} issues
- */
-async function runContributionChecks(integration, issues) {
-  await checkCodemods(integration, issues);
-  await checkTemplates(integration, issues);
-  await checkComponents(integration, issues);
-}
-
-/**
- * Validate an already-LOADED integration (as produced by
- * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
- * plus identity) and return its issues. This is the reuse seam for everyday
- * commands that have already loaded the configured integrations and want the
- * SAME validators that `validate-integration` runs, without re-resolving the
- * manifest from disk.
- *
- * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
- * already validated it (and throws otherwise), so by the time a command holds a
- * loaded integration the manifest is known-good. We re-run the on-disk
- * contribution checks (roots + codemods/templates/components) because those can
- * regress independently of the manifest (a deleted directory, a broken template).
- *
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
- * @returns {Promise<Issue[]>}
- */
-export async function validateLoadedIntegration(loaded) {
-  /** @type {Issue[]} */
-  const issues = [];
-  if (!loaded || typeof loaded !== 'object') return issues;
-  checkRoots(
-    {
-      components: loaded.components,
-      templates: loaded.templates,
-      codemods: loaded.codemods,
-    },
-    issues,
-  );
-  await runContributionChecks(loaded, issues);
-  return issues;
-}
 
 /**
  * Validate a single integration given its package directory and identity.

package/api/template/copy/copy.d.mts

@@ -4,11 +4,11 @@
 /**
  * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and
  * return the `template.copy` receipt.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @param {{targetPath: string, cwd: string, overwrite?: boolean}} ctx
  * @returns {import('../template.type.mjs').TemplateCopyResponse}
  */
-export function templateCopy(match: import("../_adapter.mjs").DiscoveredTemplate, { targetPath, cwd, overwrite }: {
+export function templateCopy(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate, { targetPath, cwd, overwrite }: {
     targetPath: string;
     cwd: string;
     overwrite?: boolean;

package/api/template/copy/copy.mjs

@@ -18,12 +18,12 @@ import {
 } from '../../../foundation/fs/path-safety.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {stripTemplateAssetRefs} from '../_adapter.mjs';
+import {stripTemplateAssetRefs} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and
  * return the `template.copy` receipt.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @param {{targetPath: string, cwd: string, overwrite?: boolean}} ctx
  * @returns {import('../template.type.mjs').TemplateCopyResponse}
  */

package/api/template/list/list.d.mts

@@ -3,11 +3,11 @@
 
 /**
  * Project a discovered template set into the `template.list` envelope.
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @param {{type?: 'page' | 'block', package?: string}} [options]
  * @returns {import('../template.type.mjs').TemplateListResponse}
  */
-export function templateList(templates: import("../_adapter.mjs").DiscoveredTemplate[], options?: {
+export function templateList(templates: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate[], options?: {
     type?: "page" | "block";
     package?: string;
 }): import("../template.type.mjs").TemplateListResponse;

package/api/template/list/list.mjs

@@ -9,11 +9,11 @@
  *   no-skeleton default) here.
  */
 
-import {pkgOf} from '../_adapter.mjs';
+import {pkgOf} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Project a discovered template set into the `template.list` envelope.
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @param {{type?: 'page' | 'block', package?: string}} [options]
  * @returns {import('../template.type.mjs').TemplateListResponse}
  */

package/api/template/show/show.d.mts

@@ -3,7 +3,7 @@
 
 /**
  * Build the `template.show` envelope for an already-resolved template.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @returns {import('../template.type.mjs').TemplateShowResponse}
  */
-export function templateShow(match: import("../_adapter.mjs").DiscoveredTemplate): import("../template.type.mjs").TemplateShowResponse;
+export function templateShow(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate): import("../template.type.mjs").TemplateShowResponse;

package/api/template/show/show.mjs

@@ -11,11 +11,11 @@
 import * as fs from 'node:fs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {extractComponents} from '../_adapter.mjs';
+import {extractComponents} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Build the `template.show` envelope for an already-resolved template.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @returns {import('../template.type.mjs').TemplateShowResponse}
  */
 export function templateShow(match) {

package/api/template/skeleton/skeleton.d.mts

@@ -5,8 +5,8 @@
  * Build the `template.skeleton` envelope for an already-resolved template.
  * `match` may be undefined when `--skeleton` is run without a name — the same
  * "specify a template name" error the dispatcher's resolution would surface.
- * @param {import('../_adapter.mjs').DiscoveredTemplate | undefined} match
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate | undefined} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @returns {import('../template.type.mjs').TemplateSkeletonResponse}
  */
-export function templateSkeleton(match: import("../_adapter.mjs").DiscoveredTemplate | undefined, templates: import("../_adapter.mjs").DiscoveredTemplate[]): import("../template.type.mjs").TemplateSkeletonResponse;
+export function templateSkeleton(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate | undefined, templates: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate[]): import("../template.type.mjs").TemplateSkeletonResponse;

package/api/template/skeleton/skeleton.mjs

@@ -11,7 +11,7 @@
 import * as fs from 'node:fs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {extractComponents} from '../_adapter.mjs';
+import {extractComponents} from '../../../foundation/discovery/template-adapter.mjs';
 
 const STRUCTURAL = new Set([
   'AppShell',
@@ -223,8 +223,8 @@ function extractSkeleton(source) {
  * Build the `template.skeleton` envelope for an already-resolved template.
  * `match` may be undefined when `--skeleton` is run without a name — the same
  * "specify a template name" error the dispatcher's resolution would surface.
- * @param {import('../_adapter.mjs').DiscoveredTemplate | undefined} match
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate | undefined} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @returns {import('../template.type.mjs').TemplateSkeletonResponse}
  */
 export function templateSkeleton(match, templates) {

package/api/template/template.d.mts

@@ -2,13 +2,13 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @typedef {import('./_adapter.mjs').DiscoveredTemplate} DiscoveredTemplate
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} DiscoveredTemplate
  */
 /**
- * @typedef {import('./_adapter.mjs').TemplateDiscoveryError} TemplateDiscoveryError
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').TemplateDiscoveryError} TemplateDiscoveryError
  */
 /**
- * @typedef {import('./_adapter.mjs').TemplateDocModule} TemplateDocModule
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').TemplateDocModule} TemplateDocModule
  */
 /**
  * @param {string} [name]
@@ -36,7 +36,7 @@ export function template(name?: string, options?: {
     type: string;
     data: unknown;
 }>;
-export type DiscoveredTemplate = import("./_adapter.mjs").DiscoveredTemplate;
-export type TemplateDiscoveryError = import("./_adapter.mjs").TemplateDiscoveryError;
-export type TemplateDocModule = import("./_adapter.mjs").TemplateDocModule;
-export { discoverAll, discoverAll as discoverTemplates, discoverAllWithErrors, discoverIntegrationTemplatesForOne, stripTemplateAssetRefs, listTemplates, findRelatedBlocks, findShowcase, extractComponents } from "./_adapter.mjs";
+export type DiscoveredTemplate = import("../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate;
+export type TemplateDiscoveryError = import("../../foundation/discovery/template-adapter.mjs").TemplateDiscoveryError;
+export type TemplateDocModule = import("../../foundation/discovery/template-adapter.mjs").TemplateDocModule;
+export { discoverAll, discoverAll as discoverTemplates, discoverAllWithErrors, discoverIntegrationTemplatesForOne, stripTemplateAssetRefs, listTemplates, findRelatedBlocks, findShowcase, extractComponents } from "../../foundation/discovery/template-adapter.mjs";

package/api/template/template.mjs

@@ -6,16 +6,16 @@
  * This module is BOTH the template dispatcher and the stable import surface for
  * the template family. `template()` discovers the available templates, resolves
  * the requested one, and routes to a leaf (list/show/skeleton/copy). The shared
- * discovery/IO + cross-command helpers live in `./_adapter.mjs` and are
+ * discovery/IO + cross-command helpers live in `foundation/discovery/template-adapter.mjs` and are
  * RE-EXPORTED here so external import paths (`api/template/template.mjs`) —
  * used by component, layout, search, init, discover, validate-integration, and
  * lib/project — keep resolving unchanged.
  *
  * @position api/template — the template dispatcher + barrel; leaves live under
- *   ./list, ./show, ./skeleton, ./copy and shared discovery under ./_adapter.
+ *   ./list, ./show, ./skeleton, ./copy and shared discovery in foundation/discovery.
  */
 
-import {discoverAll, pkgOf} from './_adapter.mjs';
+import {discoverAll, pkgOf} from '../../foundation/discovery/template-adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {templateList} from './list/list.mjs';
@@ -37,16 +37,16 @@ export {
   findRelatedBlocks,
   findShowcase,
   extractComponents,
-} from './_adapter.mjs';
+} from '../../foundation/discovery/template-adapter.mjs';
 
 /**
- * @typedef {import('./_adapter.mjs').DiscoveredTemplate} DiscoveredTemplate
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} DiscoveredTemplate
  */
 /**
- * @typedef {import('./_adapter.mjs').TemplateDiscoveryError} TemplateDiscoveryError
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').TemplateDiscoveryError} TemplateDiscoveryError
  */
 /**
- * @typedef {import('./_adapter.mjs').TemplateDocModule} TemplateDocModule
+ * @typedef {import('../../foundation/discovery/template-adapter.mjs').TemplateDocModule} TemplateDocModule
  */
 
 /**

package/api/template/template.test.mjs

@@ -4,36 +4,35 @@ import {describe, it, expect} from 'vitest';
 import {stripTemplateAssetRefs, template} from './template.mjs';
 
 describe('stripTemplateAssetRefs', () => {
-  it('replaces a lookaside astryx image URL with an inline data URI', () => {
+  it('replaces a /template-assets image path with an inline data URI', () => {
     const src =
-      "const hero = 'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png';";
+      "const hero = '/template-assets/colorful-home-horizontal-1.png';";
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces a lookaside block-avatar image URL', () => {
-    const src =
-      'src="https://lookaside.facebook.com/assets/astryx/avatar-profile-05.jpg"';
+  it('replaces a /template-assets block-avatar image path', () => {
+    const src = 'src="/template-assets/avatar-profile-05.jpg"';
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces every lookaside reference, not just the first', () => {
+  it('replaces every /template-assets reference, not just the first', () => {
     const src = [
-      "'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png'",
-      "'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-3.png'",
-      "'https://lookaside.facebook.com/assets/astryx/moody-scene-horizontal-1.png'",
+      "'/template-assets/colorful-home-horizontal-1.png'",
+      "'/template-assets/illustrative-horizontal-3.png'",
+      "'/template-assets/moody-scene-horizontal-1.png'",
     ].join('\n');
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out.match(/data:image\/svg\+xml,/g)).toHaveLength(3);
   });
 
   it('preserves surrounding source structure', () => {
     const src =
-      "const data = [{src: 'https://lookaside.facebook.com/assets/astryx/x.png', alt: 'X'}];";
+      "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
     const out = stripTemplateAssetRefs(src);
     expect(out).toContain("alt: 'X'");
     expect(out).toContain('const data = [{src:');

package/assets/codemods/transforms/v0.3.0/__tests__/migrate-grid-minchildwidth-to-columns.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../migrate-grid-minchildwidth-to-columns.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+/** Collapse whitespace (and space padding inside braces) so formatting of
+ * pretty-printed multiline objects does not matter for assertions. */
+function normalize(str) {
+  return str
+    .replace(/\s+/g, ' ')
+    .replace(/\{\s+/g, '{')
+    .replace(/\s+\}/g, '}')
+    .trim();
+}
+
+describe('migrate-grid-minchildwidth-to-columns', () => {
+  it('migrates minChildWidth only to columns={{minWidth, repeat: "fit"}}', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 280, repeat: 'fit'}}"),
+    );
+  });
+
+  it('migrates columns={n} + minChildWidth to columns={{minWidth, max, repeat: "fit"}}', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={3} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 280, max: 3, repeat: 'fit'}}"),
+    );
+  });
+
+  it('preserves other attributes (gap) when migrating the combo', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={5} gap={5} minChildWidth={140}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 140, max: 5, repeat: 'fit'}}"),
+    );
+    expect(output).toContain('gap={5}');
+  });
+
+  it('bails when columns is already an object (ambiguous)', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={{minWidth: 100}} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    // Unchanged: object columns is ambiguous, so it is left as-is.
+    expect(output).toBe(input);
+  });
+
+  it('bails when columns is a non-numeric/dynamic expression', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={cols} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('is alias-aware and supports the subpath import source', async () => {
+    const input = `import {Grid as G} from '@astryxdesign/core/Grid';
+const t = <G columns={4} minChildWidth={200}><Item /></G>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 200, max: 4, repeat: 'fit'}}"),
+    );
+  });
+});

package/assets/codemods/transforms/v0.3.0/migrate-grid-minchildwidth-to-columns.mjs

@@ -49,11 +49,10 @@ export default function transformer(file, api) {
         a.type === 'JSXAttribute' && a.name?.name === 'minChildWidth',
     );
     if (!minAttr) return;
-    const hasColumns = attrs.some(
+    const columnsAttr = attrs.find(
       (/** @type {any} */ a) =>
         a.type === 'JSXAttribute' && a.name?.name === 'columns',
     );
-    if (hasColumns) return;
 
     let minWidthExpr;
     if (
@@ -67,6 +66,43 @@ export default function transformer(file, api) {
       return;
     }
 
+    if (columnsAttr) {
+      // Both `columns` and `minChildWidth` are present. This is only safely
+      // migratable when `columns` is a numeric literal (e.g. `columns={3}`).
+      //
+      // In the old (0.2.0) Grid runtime, when both props were set and
+      // `columns` was a number, `minChildWidth` dominated and the numeric
+      // `columns` became a *max column cap* with `auto-fit`:
+      //   repeat(auto-fit, minmax(minChildWidth, 1fr)) capped at `columns`.
+      // The 0.3.0 `columns` object models this exactly as
+      //   {minWidth, max, repeat: 'fit'}.
+      // So the lossless rewrite is:
+      //   <Grid columns={3} minChildWidth={280}>
+      //     -> <Grid columns={{minWidth: 280, max: 3, repeat: 'fit'}}>
+      //
+      // If `columns` is already an object or a non-numeric/dynamic
+      // expression, the combined behavior is genuinely ambiguous, so we
+      // bail and leave it unmigrated (it surfaces separately).
+      const columnsValue = columnsAttr.value;
+      if (columnsValue?.type !== 'JSXExpressionContainer') return;
+      const columnsExpr = columnsValue.expression;
+      const isNumericLiteral =
+        (columnsExpr?.type === 'NumericLiteral' ||
+          columnsExpr?.type === 'Literal') &&
+        typeof columnsExpr.value === 'number';
+      if (!isNumericLiteral) return;
+
+      const columnsObject = j.objectExpression([
+        j.property('init', j.identifier('minWidth'), minWidthExpr),
+        j.property('init', j.identifier('max'), j.literal(columnsExpr.value)),
+        j.property('init', j.identifier('repeat'), j.literal('fit')),
+      ]);
+      columnsAttr.value = j.jsxExpressionContainer(columnsObject);
+      attrs.splice(attrs.indexOf(minAttr), 1);
+      hasChanges = true;
+      return;
+    }
+
     const columnsObject = j.objectExpression([
       j.property('init', j.identifier('minWidth'), minWidthExpr),
       j.property('init', j.identifier('repeat'), j.literal('fit')),

package/assets/docs/layout.doc.dense.mjs

@@ -64,7 +64,7 @@ export const docsDense = {
             'no Card-wrapped list items (card soup)',
             'no stacked full-width Cards as page structure',
             'no Cards in Cards',
-            'no decorative Badge — counts/enums only; StatusDot/Token for status',
+            'no decorative Badge: counts/enums only; StatusDot/Token for status',
           ],
         },
       ],

package/assets/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx

@@ -10,7 +10,7 @@ export default function AspectRatioCircleImage() {
     <Center width={300}>
       <AspectRatio ratio={1} shape="ellipse" fit="cover">
         <img
-          src="https://lookaside.facebook.com/assets/astryx/light-home-square-1.png"
+          src="/template-assets/light-home-square-1.png"
           alt="Circular image"
         />
       </AspectRatio>

package/assets/templates/blocks/components/AspectRatio/AspectRatioImageGallery.tsx

@@ -27,7 +27,7 @@ export default function AspectRatioImageGallery() {
         {images.map(({id, alt}) => (
           <AspectRatio key={id} ratio={4 / 3} fit="cover">
             <img
-              src="https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-1.png"
+              src="/template-assets/illustrative-horizontal-1.png"
               alt={alt}
               style={{borderRadius: 8}}
             />