Files
prometeu-studio/discussion/lessons/DSC-0109-pbs-logical-viewport-composition/LSN-0108-composition-reference-coverage-and-studio-boundaries.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

10 KiB

id, ticket, title, created, tags
id ticket title created tags
LSN-0108 pbs-logical-viewport-composition Composition Reference Coverage and Studio Boundaries 2026-11-10
studio
composer
documentation
diagnostics

Original problem and accepted outcome

Owner: studio, composition knowledge and authoring support independent of UI. Discussion: DSC-0109, originating in AGD-0111.

A separate Zelda port exposed difficulty understanding the relationship between terrain, camera, sprites, HUD, Gfx overlays and frame clearing. It also needed to fit its original image into the Prometeu framebuffer. These observations prompted an evaluation of useful support in Studio.

The user accepted the completed evaluation on 2026-11-10, requested coordination with the umbrella and then explicitly requested housekeeping. The accepted outcome is to retain the existing Studio product interfaces for this scope and record the documentation/example gaps for the compiler/pbs content owner. No Studio feature or service change was justified by the evaluated cases.

The evaluation and coordination are complete. No product implementation remains in this discussion. The user requested direct housekeeping of this accepted evaluation; no implementation plan or artificial code-change stage was created. This lesson preserves the accepted conclusion after removal of the agenda.

Responsibility boundaries

  • The game project owns its presentation policy: viewport placement, borders, offsets and rules needed to reproduce its original game. Existing HUD/layer composition may implement borders, for example.
  • Studio owns its integration of project knowledge and its existing automation services. The language/SDK provider owns the content of its references.
  • The runtime retains its existing execution and rendering contracts. This discussion did not authorize runtime changes or commits.
  • All UI improvements were excluded because a Studio UI replacement is planned. That exclusion also prevents speculative services created only for a future UI.
  • General authoring problems remain worth evaluating even if first observed in a single game. Their origin does not make every local workaround a tool feature.

What the audit established

Studio already exposes the project reference index through studio_project_context and paginated text through studio_reference_read. CompilerProjectKnowledge selects installed provider references for the current project's SDK/target. The PBS build projects its canonical specifications, SDK resources and example files into the installed reference index.

The installed Game/SDK 1 bundle contained 176 reference entries:

Kind Entries
SEMANTICS 40
SYNTAX 1
QUICKSTART 1
SDK 28
EXAMPLE 106

EXAMPLE counts indexed files, not independent example projects. All 176 resources matched their indexed SHA-256 hashes. The isolated installed probe paginated every reference through the Studio knowledge service and reconstructed exactly the provider's text. No reference-delivery defect was demonstrated in this scope.

The runtime's graphics specification is not an input of the PBS reference build. Its absence from that catalog is not evidence that Studio dropped a page.

Content coverage

Topic Existing coverage Remaining content opportunity
Composer/Gfx order PBS chapter 5 calls Gfx primitive/overlay-oriented; bindings and signatures are available. Explain final overlay order and why a clear can cover composed content.
Layers, priority and transparency Parameter descriptions and the sprite-emission signature exist. Explain operational composition with a small example, without assuming NES equivalence.
Camera, sprites and HUD Camera bindings and sprite screen-coordinate descriptions exist. Demonstrate the relationship between coordinate spaces and caller-owned transforms.
Empty background and clearing Isolated Gfx examples exist. Explain existing scene/no-scene behavior and demonstrate an appropriate empty-scene setup.
Visual query versus animation advance PBS chapter 27 explicitly separates query/emission from playback advance. No additional work justified by this question.
Fixed terrain and mutable objects No complete general composition example was found in the audited example files. Evaluate a neutral example independent of any port.

src/main.pbs draws a moving Gfx rectangle. The production Gfx example uses fill_rect. src/animation.pbs includes a helper calling emit_sprite, but the audited PBS example files do not call Composer.bind_scene or Composer.set_camera. These facts identify a content opportunity, rather than a missing Studio operation.

The existing runtime contracts and sources were inspected read-only to check the reported behavior. Future explanatory material must distinguish public contract from implementation observations and preserve runtime ownership of execution.

Recorded handoff to compiler/pbs

The owner of the distributed Composer/Gfx documentation and Game SDK 1 examples can evaluate the following work in its own scope:

  1. Improve explanations of composition order, coordinate spaces, priority, transparency and clearing, using the existing execution contracts as authority.
  2. Evaluate one complete neutral example with minimal owned resources, terrain, actor, HUD, camera movement and mutable objects. Reuse the current reference mechanism and SDK APIs; keep game-specific layout and occlusion policy local.
  3. If an example is produced, qualify compilation, graphical execution and pixel expectations separately through the existing headless path. A successful compile alone does not establish correct visual output.

This handoff records a destination and concrete content gaps. It does not open a new discussion, authorize implementation in another domain or promise a new SDK API. Studio must not compensate with duplicated specifications or diagnostics that classify valid game presentation choices as errors.

Verification and evidence

The audit used Studio revision b351f2e5823039f82e3cd9666547578add13bebb. The installed frontend JAR SHA-256 was 780dc6f72755692731291d169d6f161eb47d0401579731753c5f59aa4a702f0e.

13 tests passed, with no failures, errors or skips:

Suite Tests What it verifies
ProjectReferencesTest 6 Studio reference integration, pagination, SDK selection and unavailable-reference handling.
PbsDocumentationTest 5 Provider/index consistency, exact SDK resources and supported selection.
InstalledKnowledgeTest 2 Isolated installed-JAR reads, complete paginated text and example compilation.

The installed task was explicitly executed with --rerun; the result was not merely reused from Gradle's up-to-date state.

./gradlew :prometeu-app:test --tests p.studio.app.compiler.ProjectReferencesTest :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests p.studio.compiler.pbs.documentation.PbsDocumentationTest --console=plain
./gradlew :prometeu-app:installedKnowledgeTest --rerun --console=plain

Preserved evidence:

The audit did not execute graphical rendering, compare pixels or exercise a complete authenticated MCP HTTP session. Its evidence covers the neutral knowledge integration, installed texts and compilation, not visual correctness. No product code, specification, UI, SDK, runtime or port was changed.

Coordination and remaining work

The DSC-0104 / AGD-0106 umbrella preserves this accepted outcome as an external interface, preserving its existing compiler reliability and diagnostics scope and its two agreed deliveries. This content handoff does not become a new child, implementation gate or prerequisite for closing that umbrella. The related assets discussion refers to this lesson for the completed knowledge evaluation; it retains its own authoring/budget scope.

The prior DSC-0108 installed examples lesson remains valid. This later audit identifies composition coverage outside its qualified corpus and does not reinterpret its acceptance or claim that graphics were already tested there.

No further Studio implementation is pending for DSC-0109. Potential content work remains a recorded handoff for its owner; UI improvements remain outside this ticket and require their own future scope.

Common mistakes

  • Treating difficulty adapting a game's presentation as proof of a runtime gap.
  • Adding a Studio endpoint before checking existing knowledge and headless APIs.
  • Confusing incomplete source content with a broken Studio reference index.
  • Duplicating language/SDK specifications in Studio to make text more accessible.
  • Counting compilation or a reference hash match as proof of pixel correctness.
  • Allowing a deferred UI feature to introduce speculative backend obligations.
  • Reopening an umbrella's accepted deliverables through an external content handoff.

Maintenance references