>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588809. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Currently <code>global.css</code> ships as part of the component upload &mdash; embedded in the component bundle or referenced as a global attachment. This approach has two problems:</p> <ul> <li><strong>Coupling:</strong> when CSS needs updating, the component bundle must be re-uploaded even if the component logic didn't change. Asset libraries are config entities &mdash; they can be updated independently via PATCH without re-uploading component code.</li> <li><strong>Scope:</strong> <code>global.css</code> is shared across all components. Shipping it inside a component bundle means one component "owns" the global styles &mdash; creating arbitrary dependencies and making deletion or replacement of that component risky.</li> </ul> <p>The <code>canvas:asset_library</code> OAuth scope is confirmed in the official canvas_oauth module (not inferred). It grants <code>administer code components</code> Drupal permission and exposes <code>/canvas/api/v0/config/asset_library</code> for GET/POST/PATCH/DELETE. The jamie-demo's <code>.env.example</code> already lists <code>canvas:asset_library</code> at line 28 (<code>CONTENT_OAUTH_SCOPE=canvas:js_component canvas:asset_library member</code>), so the infrastructure is already in place &mdash; just not yet used as a formal migration phase.</p> <p>A Canvas asset library cleanly separates shared CSS from component code. Phase 5.5 formalizes asset library setup as a discrete step with clear inputs and outputs.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a migrate-site upload phase. Inspect what owns <code>global.css</code>: it ships inside a specific component bundle (e.g., <code>site-header</code>) or is referenced via a global attachment.</li> <li>Update <code>global.css</code> after migration.</li> <li>Observe: re-upload of the owner component is required even though the component logic is unchanged. Removing or replacing the owner component risks losing the global styles.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Understand current <code>global.css</code> handling.</strong> Read <code>canvas-storybook-ai/CLAUDE.md</code> and the current SKILL.md Phase 4 to determine exactly how <code>global.css</code> is currently deployed (inside a specific component bundle, separate step, or external link). Document current state before changing it.</p> <p><strong>Step 2 &mdash; Probe the asset library endpoint:</strong></p> <pre>POST /canvas/api/v0/config/asset_library Authorization: Bearer &lt;canvas:asset_library token&gt; Content-Type: application/json { "id": "global-styles", "label": "Global Styles", "css": { "theme": { "global.css": {} } }, "js": {}, "dependencies": [] }</pre><p>If POST succeeds, document the payload structure in <code>gotchas.md</code>. Check whether the response includes the registered asset library ID for subsequent PATCH updates.</p> <p><strong>Step 3 &mdash; Write <code>scripts/setup-asset-library.mjs</code></strong> (reads <code>global.css</code> from migration artifacts &rarr; POSTs/PATCHes to <code>/canvas/api/v0/config/asset_library</code>):</p> <pre>const globalCss = readFileSync('docs/migration/global.css', 'utf8'); const token = await getToken('canvas:asset_library'); const existing = await fetch( `${SITE_URL}/canvas/api/v0/config/asset_library/global-styles`, { headers: { Authorization: `Bearer ${token}` } } ); const method = existing.ok ? 'PATCH' : 'POST'; const url = existing.ok ? `${SITE_URL}/canvas/api/v0/config/asset_library/global-styles` : `${SITE_URL}/canvas/api/v0/config/asset_library`; await fetch(url, { method, headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` }, body: JSON.stringify({ id: 'global-styles', label: 'Global Styles', css: { inline: globalCss } }), });</pre><p><strong>Step 4 &mdash; Add Phase 5.5 to <code>migrate-site/SKILL.md</code></strong> between Phase 5 (media) and Phase 6 (site-config):</p> <pre>PHASE 5.5 &mdash; Asset library setup (conditional: only if global.css or shared JS bundles exist) 1. Read docs/migration/components/global-styles.md (or equivalent) for global CSS content 2. Check scope-availability.json (from 1-08) for canvas:asset_library "confirmed" 3. POST/PATCH to /canvas/api/v0/config/asset_library with canvas:asset_library token 4. Verify asset library is accessible on the live site 5. Log workflow/phase5.5-asset-library-checklist.json</pre><p><strong>Step 5 &mdash; Update <code>component-builder.md</code>:</strong> "Global CSS should be placed in an asset library config entity (Phase 5.5), not embedded in a component bundle. Components ship JS + component-scoped styles only."</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Document current <code>global.css</code> handling before changing.</li> <li>Probe <code>POST /canvas/api/v0/config/asset_library</code> with a <code>canvas:asset_library</code> token; document payload schema in <code>gotchas.md</code>.</li> <li>Write <code>scripts/setup-asset-library.mjs</code>.</li> <li>Add Phase 5.5 section to <code>SKILL.md</code> with conditional skip logic and scope-availability gating.</li> <li>Update <code>component-builder.md</code>: components no longer ship global CSS.</li> <li>Verify on a staging instance: asset library created/updated; global CSS visible on the live site after Phase 5.5 run (not from component bundle).</li> <li>Coordinate the migration of any component that currently bundles <code>global.css</code> to avoid a moment where neither source has the CSS.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None directly. Operationally, global CSS becomes independently updatable post-migration &mdash; content/styling teams can iterate on global styles via PATCH without re-uploading any component bundle.</p> <h3 id="summary-api-changes">API changes</h3> <p>The phase consumes (does not introduce):</p> <ul> <li><code>GET /canvas/api/v0/config/asset_library/&lt;id&gt;</code> &mdash; existence check.</li> <li><code>POST /canvas/api/v0/config/asset_library</code> &mdash; create.</li> <li><code>PATCH /canvas/api/v0/config/asset_library/&lt;id&gt;</code> &mdash; update.</li> <li>All with a <code>canvas:asset_library</code> scoped token.</li> </ul> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact: <code>docs/migration/workflow/phase5.5-asset-library-checklist.json</code>. Component bundles no longer carry <code>global.css</code> after Phase 5.5 lands.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-8-Patterns-To-Encode/08-NEW-10-asset-library-phase.md</code> (id: NEW-10)</li> <li>Scope reference: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code> &sect; canvas_oauth scopes &mdash; canvas:asset_library</li> <li>Canvas OpenAPI spec: <code>https://git.drupalcode.org/project/canvas/-/blob/1.x/openapi.yml</code></li> <li>jamie-demo project config: <code>.env.example</code> line 28 &mdash; <code>canvas:asset_library</code> already in <code>CONTENT_OAUTH_SCOPE</code></li> <li>Sibling phase: <code>Sprint-8-Patterns-To-Encode/07-NEW-9-content-model-setup-phase.md</code> (issue 8-07)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Exact payload format for creating a Canvas asset library config entity? canvas_oauth README lists the endpoint but not the request body schema. Check the OpenAPI spec.</li> <li>When a Canvas component references an asset library, does the asset library ID need to be declared in <code>component.yml</code>, or does it auto-load globally? Determines whether component bundles need changes when asset library is introduced.</li> <li>Does <code>canvas:asset_library</code> grant the same <code>administer code components</code> Drupal permission as <code>canvas:js_component</code>? Scope table says yes &mdash; if so, a single token may cover both.</li> <li>Currently, does any component in the project have <code>global.css</code> baked into its bundle? If so, removing it requires a coordinated update so styles are not lost between source and asset-library activation.</li> </ul>