Default Template Bundle Laravel Package

Getting Started

• Install with composer require os2display/default-template-bundle:^2.2. The release is additive (dark mode support only), so it is a safe in-place bump from 2.x — no migrations, no renamed services, no removed templates.
• Look first at Resources/views/ (the default slide templates) and DependencyInjection/ (where templates are registered as tagged services). That pair tells you what you can render and what you can override.
• Know what you are integrating: this is a Symfony bundle, not a Laravel package. It is useful to you directly if your rendering layer is Symfony/Twig, or indirectly if you are pulling its Twig templates into a Laravel app that already speaks Twig (or you are porting markup into Blade). There is no service provider, no config file to publish, and no facade.
• Confirm how templates are discovered in your host app: templates typically resolve through the bundle path plus a tagged-service registry, so the bundle must be enabled/registered before your first render or you will get an empty template list rather than an error.
• First use case: render one default slide template in your layout, then flip the new dark mode variant on and confirm your surrounding chrome (header/footer/player UI) does not clash. Do this before touching anything else — 2.2.0 is largely a styling contract change, and that is exactly where host apps break.
• Run your asset pipeline once after install (assets:install/cache:clear on Symfony, npm run build on the host) so the new dark mode styles actually land in your public directory.

Implementation Patterns

• Pin to the minor, upgrade for the feature. Use ^2.2 and let patch releases flow. Because 2.2.0 is a single merged PR adding dark mode, treat it as a styling-only upgrade: bump, rebuild assets, visually diff one slide of each template type you actually use.
• Theme switching at the wrapper, not the template. Prefer driving dark mode from a single ancestor attribute/class on your app shell (e.g. data-theme="dark" or a .dark root) and letting the bundle's templates inherit. Do not fork the bundle's templates just to add a class per slide — you lose the upgrade path and every future template fix.
• Override by path, keep it surgical. If you must customise a template, copy only the one file you need into your host templates directory using the same relative path the bundle uses, and leave the rest untouched. Keep a short list of overridden paths in your repo; that list is your upgrade checklist.
• Register/override templates through the same tagged-service mechanism the bundle uses rather than hardcoding template IDs in application code. This keeps new templates shipped in future releases automatically available to your slide picker.
• Treat the template set as data, not code. Feed your slide/screen entities the template identifier and let the bundle resolve the view. This is what makes a template-bundle upgrade a non-event in your domain layer.
• CI guard for visual regressions. Now that a light and dark presentation exist, add a cheap snapshot or screenshot test of one representative slide per template in both modes. It catches the real failure mode of this release: text/background contrast that only breaks in the mode you do not develop in.
• Composer constraints in a monorepo. If several apps share the bundle, pin them all to ^2.2 in the same change window so a slide authored with dark-mode tokens is not rendered by a 2.1 host that has no styles for them.

Gotchas and Tips

• The most likely breakage is invisible in a diff. Dark mode ships CSS, so nothing fails loudly — you get dark backgrounds with your host app's dark text, or your own hardcoded brand colours fighting the bundle's tokens. Grep your project for hardcoded hex values in slide-related CSS and move them to variables.
• Assets are not reinstalled by composer update. Public/vendor asset copies are stale until you re-run the install/rebuild step. If dark mode "does nothing" after the upgrade, this is almost always the cause, followed by cached CSS or a stale service worker on the player.
• Clear the cache after the bump. Template registration is cached in compiled container/route caches; a stale cache will show you the old template list and make you think the feature is missing.
• Verify the trigger, not just the styles. Check what the bundle actually keys dark mode off — a wrapper class, a media query, or a data attribute. If it only implements prefers-color-scheme, a manual toggle in your UI will not work, and you will need to wrap or override.
• Overrides shadow new releases. Any template you copied before 2.2.0 will still be the light-only version after the upgrade. Re-copy it (and re-apply your diff) or you will have a slide that silently ignores dark mode while its siblings honour it.
• Do not assume the light mode is untouched. A PR labelled "darkmode support" frequently refactors shared colour declarations. Re-check the light rendering of at least the templates you depend on before promoting to production.
• This is not a Laravel package. If the surrounding codebase expects config/*.php publishing, facades, or Blade components, budget for a translation layer (or a thin wrapper) rather than expecting the bundle to behave like a Laravel vendor package. That friction is the main cost of adoption, not anything in 2.2.0.
• Report regressions upstream. The change is a single merged PR; dark mode contrast issues and template-specific colour bugs are best raised as issues against the bundle rather than patched locally, so you keep the upgrade path clean.