Starterkit Larawire Agentic Laravel Package

Getting Started

This is a Laravel starter kit package (aldhi88/starterkit-larawire-agentic) that ships prebuilt theme assets (DashCode, Tabler, Vuexy), host-owned view overrides, and artisan tooling to keep them synchronized. v1.9.0 is a backward-compatible minor, so the first job is simply to pull it in and see what changed in your host overrides.

1. Upgrade the dependency and re-sync assets:

   composer update aldhi88/starterkit-larawire-agentic
   php artisan starter:sync
   

2. Look at your overrides before you replace anything. This is the single most important first step in this release:

   php artisan starter:views-status
   php artisan starter:views-replace --dry-run
   

   The crop workflow touches the profile/logo markup, so any host-owned override of the avatar, logo, or branding partial will show up as drifted here.
3. Try the first use case end-to-end: go to the profile settings page, upload a logo, and walk the new Canvas cropper — pointer drag to position, wheel/zoom control, keyboard arrows to nudge, contain vs cover toggle for transparent sources, confirm, and observe that only the approved 800×200 PNG is handed to Livewire. Repeat with a favicon (256×256).

Where to look first: the published override directory (per theme), the starter kit config file for upload/validation limits, and the Livewire profile component that consumes the cropped export. The cropper is dependency-free vanilla Canvas, so there is no npm/Vite build step to configure and no third-party JS to audit — a genuine plus for day-to-day maintenance.

Implementation Patterns

Export-then-upload, not file-input-then-upload. The pattern this release enforces is: the browser holds the source image, the Canvas produces an approved PNG blob, and only that blob is attached to the Livewire property. Treat the cropper as a pre-processor. Your Livewire component should expect a properly sized PNG and should not attempt to re-crop server-side.

Wire it into Livewire with an explicit commit step. Typical shape:

• wire:model a temporary upload or use a plain <input type="file"> read via FileReader into the canvas,
• keep crop state (offset, zoom, mode) in Alpine or plain JS local to the component,
• on "Save", call canvas.toBlob() and push the blob into the Livewire upload property, then dispatch the save action.

Because the release guards submission during decode/crop/upload, disable your own submit button on the same lifecycle events rather than relying solely on the package guard — belt and braces, and it keeps your custom buttons consistent.

Respect the Cancel contract. Cancel must preserve both the previously saved asset and any pending asset, and a failed upload must remain retryable. In practice: never destroy the current media record until the new upload's ->store() succeeds, and keep the retry path open by not clearing the source image on error. If you add custom UI around the modal, mirror those semantics.

Theme-specific overrides, one workflow. You have three theme families. Keep a single documented customization path per theme and re-run starter:views-status in CI so override drift is visible on every dependency bump, not discovered in production. The --dry-run diff is your review artefact — merge business customizations into the new view before running starter:views-replace for real.

Production deploys are a different command. Locally and in CI: starter:sync, commit the lockfile plus synchronized assets. In production: composer install --no-dev --optimize-autoloader then php artisan starter:deploy. Never run starter:sync in production — encode that as a rule in your deploy docs and, ideally, a guard in your pipeline.

Rollback is a pin, not a revert. If the cropper misbehaves in a specific browser, pin 1.8.0, reinstall dependencies, re-run the normal sync workflow, and redeploy. Keep the previous tag deployable.

Testing. Assert on the exported dimensions (800×200 / 256×256) and MIME type in a browser test or a JS unit test around the canvas module; server-side, keep your existing validation tests since authoritative validation is unchanged by this release.

Gotchas and Tips

• Client limits are 10 MB, 8192 px per side, and 32 MP. The megapixel ceiling is the one that bites: a 32 MP image decodes to roughly 128 MB of RGBA in the canvas. If you expect large phone photos, raise memory_limit for that request path and verify mobile Safari, which is the tightest on canvas memory.
• The crop is UX, not security. Server validation is explicitly unchanged. Do not remove or loosen your server-side image/mimes/dimensions rules because the client "guarantees" a PNG.
• Transparency only survives as PNG. The export is PNG-only, which is why decorative backgrounds, borders, and shadows were stripped from navigation logos. If you re-add a CSS background or shadow behind the logo in your override, you reintroduce the exact problem this release fixed — keep the logo container transparent.
• contain vs cover changes the visual result, not the canvas size. Both export 800×200. contain letterboxes transparently (good for wide wordmarks); cover fills and crops (good for square-ish marks). Pick per asset type and document it, or support staff will file bugs about "cut off" logos.
• SVG is not accepted. Only PNG, JPG, WebP. If your brand assets are SVG, you need to rasterize upstream — the cropper will not help.
• JPG sources become opaque. Transparent export of a JPG source has no alpha to preserve; expect a solid background. Choose PNG/WebP sources when transparency matters.
• Keyboard accessibility is part of the contract. Pointer and keyboard positioning plus accessible modals shipped here. If you build a custom trigger or modal wrapper, verify tab order, escape-to-cancel, and focus return — you can easily break the a11y work with your own markup.
• Overrides drift silently on minor releases. The version is backward-compatible, but the profile/logo markup changed. starter:views-status + starter:views-replace --dry-run before any real replacement, every time. Merging blindly will drop your business customizations.
• Commit synchronized assets. starter:sync output is part of your repo; forgetting it produces a production build whose views and assets disagree. Cache-busting on published theme assets is another reason to keep them in the lockstep commit.
• Extension points: the cropper is dependency-free vanilla JS, so the natural extension points are your host-owned overrides (modal markup, trigger button) and the config-driven size/limit values — not forks of the package. If you need a different export size than 800×200 / 256×256, that is a package-level request, not an override.
• Debugging tips: if the confirm button seems dead, check whether submit is guarded mid-decode; if the upload retries keep failing, confirm you kept the source file in memory rather than revoking the object URL on error; if the logo renders with a grey box, look for inherited background-color/box-shadow in your override.