Engine Laravel Package

Technical Evaluation

Architecture fit. torchlight/engine is the PHP-side rendering core of the Torchlight annotation system. Architecturally it is a strong fit for a Laravel monolith because it lets code highlighting and annotation run in-process rather than round-tripping code to the hosted Torchlight API. That is the central architectural value: it removes a third-party network hop, eliminates sending source snippets off-premises, and decouples rendering cost from API quotas. It is not a general-purpose highlighter (it is not a replacement for spatie/laravel-markdown or league/commonmark); it is purpose-built for the Torchlight annotation syntax (line highlighting, diffs, focus ranges, labels). v1.0.0 resolves the biggest open architectural question in the prior assessment: "Phiki 2 Support" confirms the engine is a wrapper over Phiki, the pure-PHP port of Shiki. That means TextMate grammars and themes are consumed in PHP with no Node or WASM runtime — the materially better operational story we hoped for. It also means the engine inherits Phiki's grammar/theme fidelity characteristics and Phiki's release cadence.

Integration feasibility. Composer-installable, MIT-licensed, now at a stable 1.0.0. The 1.0.0 designation is the headline change: it implies a semver contract and an end to arbitrary API churn, which was previously an explicit risk. Feasibility friction now shifts almost entirely to the dependency graph. The release notes bundle two distinct things — reaching 1.0.0 and adopting Phiki 2 — and we cannot tell from the notes whether Phiki 1 is still supported via a widened constraint or has been dropped. That single fact determines whether this is a routine upgrade or a forced migration for anyone already pinned.

Technical risk. The prior risk profile changes meaningfully, in both directions:

• Reduced: pre-1.0 API churn is largely retired. A 1.0.0 tag is a reasonable signal that the maintainers intend the public surface to be depended upon, which is also consistent with the umbrella torchlight/torchlight-laravel client planning to consume it.
• Reduced: the "is there a Node/WASM runtime?" question is answered — no. Phiki is PHP-native. Deployment stays a plain Composer install.
• Increased / newly visible: we now have a second upstream on the critical path. Phiki is a separate project with its own maintainers, its own release cadence, and its own grammar/theme fidelity relative to Shiki. A Phiki major bump can change tokenization output even if torchlight/engine is unchanged, which directly threatens our rendered-HTML parity.
• Increased / newly visible: a 0.x → 1.0.0 jump that simultaneously adopts a new major of a core dependency is, in practice, a breaking-change release regardless of the version number. Do not treat "1.0.0" as "safe minor."
• Unchanged: single-vendor concentration, and the "0 dependents / early adopter" signal from the prior assessment. The new release notes do not change that; we would still likely be among the first production consumers.
• New signal, minor but real: the changelog is vague ("Refactors, bug fixes and new features! Consult the readme :)"). For a package rendering user-visible output, "read the readme" is not an adequate change record. It raises the cost of every future upgrade review and is a soft indicator of release-discipline maturity.

Key questions to resolve before committing.

• What is the new PHP and Laravel version support matrix at 1.0.0, and does 1.0.0 drop any versions we still run?
• Does 1.0.0 require Phiki 2, or support both Phiki 1 and 2 via a widened constraint? If it drops Phiki 1, what breaks for existing pins?
• Does Phiki 2 change tokenization output versus Phiki 1 (grammar versions, theme resolution, whitespace/<span> nesting)? This is the single highest-value thing to test, because it is exactly what our parity harness checks.
• Are grammars and themes bundled with Phiki, downloaded, or user-supplied, and is there any network call at boot or install?
• Is this now a drop-in local driver behind the existing torchlight/torchlight-laravel client, or still a parallel API we must wire up ourselves?
• Does rendering happen at request time or can it be pre-rendered at build/deploy time? (Unresolved and unchanged from before — still the biggest operational unknown.)
• What is the per-code-block render cost (p50/p95) and memory ceiling for large blocks, on Phiki 2 specifically?
• Is there an explicit stability/BC policy now that 1.0.0 exists, and who maintains Phiki if the Torchlight maintainers are not the same people?
• Is there any commercial support tier tied to a Torchlight subscription, or is this purely community-supported?

Integration Approach

Stack fit. Laravel + Composer, auto-discovered provider, config-published defaults. The engine plausibly slots in beneath the existing Torchlight Blade directive / Markdown extension surface, so application code using torchlight fences should not need to change. If it does require application-level changes, treat that as a scoping surprise and re-evaluate. Add Phiki to the stack-fit review as a first-class component, not an invisible transitive: its version, its grammar/theme sourcing, and its maintainership now matter to us.

Migration path. The realistic migration is still from the hosted API to local rendering, but the sequencing now has an important refinement — upgrade and adoption are two separable decisions and should be evaluated separately:

1. Pin the current torchlight/torchlight-laravel version and capture baseline rendered HTML for a representative corpus (docs pages, blog posts, README renders, changelog diffs). Include deliberately awkward blocks: long lines, nested lists, diffs, focus ranges, non-ASCII, unknown languages.
2. First test: install torchlight/engine 1.0.0 on a feature branch and check only whether the lockfile resolves. Confirm which Phiki major it pulls and whether that conflicts with anything already in the graph.
3. Render the same corpus and diff outputs byte-for-byte. Classify divergences into (a) cosmetic whitespace, (b) token/grammar differences, (c) annotation feature gaps. Attribute each divergence to engine or to Phiki 2 where you can — it tells us who to file upstream with and where our fork contingency would live.
4. Benchmark p50/p95 render time and peak memory on the corpus, on Phiki 2.
5. Gate cutover on parity + performance thresholds, then roll out per environment (dev → staging → prod), keeping the API path behind a config flag for one release cycle.

Compatibility. Verify the Composer constraint graph against our lockfile first — a transitive PHP, illuminate/*, or Phiki conflict is the most likely blocker and is cheap to check before any engineering time is spent. Specifically determine whether the engine now pins phiki/phiki:^2 and whether that collides with anything else in our graph that also uses Phiki. Also confirm whether the engine and the current hosted-API client can coexist (dual-path rollout) or are mutually exclusive.

Sequencing. Dependency check (including Phiki) → spike on a throwaway branch → parity harness → performance gate → feature-flagged rollout → remove API credentials and egress rules → decommission API config. Two amendments from this release: (a) treat the 1.0.0 upgrade and the Phiki 2 upgrade as one atomic unit — do not attempt to land them across separate PRs; (b) do not sequence credential removal before the flag has been dark-launched in production for at least one full release, now with the caveat that a Phiki patch release can change rendering under us, so keep the baseline corpus render as a CI check rather than a one-time exercise.

Operational Impact

Maintenance. MIT license is permissive and fork-friendly, and 1.0.0's semver intent reduces the frequency of forced work. But the maintenance surface has widened, not narrowed: we now track two upstreams (torchlight/engine and phiki/phiki) plus their grammar/theme data. The vague changelog means each upgrade requires reading the readme and, realistically, diffing rendered output rather than reading release notes. Budget for that. The fork contingency should be documented at the Phiki layer as well as the engine layer — if grammar fidelity is the problem, forking the engine does not help.

Support. No evident commercial SLA unless tied to a Torchlight subscription. Primary channel remains GitHub issues and maintainer responsiveness — now across two repositories. For a package on the critical path of documentation rendering, that is acceptable only if we accept that we may need to patch locally. 1.0.0 slightly improves our confidence that the maintainers intend to support the public API; it says nothing about response times or SLA.

Scaling. Unchanged in substance and still the most important operational shift: rendering CPU moves from Torchlight's infrastructure onto our app servers. If rendering is request-time, pages with many code blocks will show measurable p95 regression, and PHP-FPM worker saturation becomes a new failure mode under traffic spikes. Phiki 2 is a plausible performance change in either direction — re-baseline rather than assume the old numbers carry over. Mitigations: cache rendered HTML keyed by content hash, pre-render at build time where content is static (docs, blog), and set a hard cap on block size. If the engine supports build-time rendering, prefer that path for anything not user-generated.

Failure modes to instrument for.

• Grammar or theme load failure at boot → blank or unstyled output, potentially fatal if unguarded.
• Silent tokenization drift from a Phiki patch/minor bump — rendering changes without any engine version change. This is the new top-of-list risk and the reason the parity harness must be a standing CI check keyed by content hash.
• PHP memory exhaustion on very large code blocks.
• Silent output divergence from the previous renderer (breaks copy-paste, anchor links, or snapshot tests).
• A forced migration if engine 1.0.0 has dropped Phiki 1 support and we later need to roll back one but not the other.
• Dependency conflict on a routine composer update that blocks unrelated work.

Ramp-up. Low. Any Laravel developer can install and configure this in an afternoon; the only genuinely new surface is the annotation syntax and the grammar/theme configuration model — and the grammar/theme model is now Phiki's, which is well-documented territory (Shiki-compatible TextMate themes). The real ramp-up cost remains the parity harness and the performance baseline, a few days of TPM-visible effort that should be scheduled explicitly rather than assumed.

Recommendation. Proceed to a time-boxed spike — the same recommendation as before, but with materially better inputs. The blocking architectural unknown (Node/WASM runtime) is now resolved in our favor, and 1.0.0 retires the pre-1.0 churn risk. What replaces those risks is dependency depth: Phiki is a second upstream on the critical path, and 1.0.0 is effectively a breaking-change release because it lands a Phiki major bump alongside it. Gate the decision on (1) lockfile resolution including Phiki, (2) token-level parity against the baseline corpus, and (3) the p95 benchmark on Phiki 2. If all three pass, adopt — with the vendored/fork contingency documented at both the engine and Phiki layers from day one, and the parity harness retained permanently as a CI gate rather than a one-off migration artifact.