Add package-level datasource declarations

[corepunch]

Summary

This PR implements the datasource provider gateway pattern — package.lua declares named data sources, views bind to them by name, and providers handle fetch/save/revert behind a message-driven contract.

Architecture

package.lua                  registry                   view XML
---                           ---                        ---
DataSources = {       FS_RegisterDataSource()   DataContextSource="ApplicationData"
  { Name="AppData",                              ItemsSource="ApplicationData:Metrics"
    Type="Xml",                      
    Params="Path=...",            FS_ResolveDataSource("AppData")
    Schema="..." }                             
                                        _xml_ds_fetch(params)
                                                  |
                                           FS_LoadObject(path)
                                                  |
                                          DataObject tree
                                                  |
                                          DataContext / ItemsSource

How it's done

Provider registry (filesystem.c):

• Static arrays for provider types (type_name + fetch/save/revert callbacks), datasource entries (name, type, params, owning project, generation), and runtime sessions (cached root, dirty flag, optional schema).
• FS_RegisterDataProvider accepts fetch + save + revert callbacks.
• FS_RegisterProjectDataSource stores entries with project ownership.
• FS_ResolveDataSource checks session cache first, then walks entries → finds matching provider type → calls fetch → caches in session.
• Project-scoped cleanup via FS_ClearProjectDataSources (removes entries + invalidates orphaned sessions). Full reset via FS_ClearAllDataSources.

Lifecycle (w_filesystem.c):

• filesystem.init → FS_LoadBundle → registers each DataSource via FS_RegisterProjectDataSource, passing the optional Schema field appended to params as &Schema=....
• filesystem.unloadProject → FS_ClearProjectDataSources + OBJ_Clear + OBJ_RemoveFromParent.
• Project.Object.Release handler fires on object destruction as a safety net.

Master-detail (UIKit.cgen, ListBox.c, object_hierarchy.c):

• ItemsControl.SelectedItem (DataObject*) added to the .cgen, auto-generated as a struct field with property ID/short-ID registration.
• ListBox sets SelectedItem = itemNode->DataContext in ListBox_SetSelected (and ListBox_SyncToSelectedValue for binding-driven changes).
• OBJ_FindPropertyByPath extended: when a path segment isn't a child object, it tries finding an object-typed property, reads the component pointer, calls CMP_GetObject, and continues resolution on the pointed-to object. This enables paths like SelectedItem/Title.

Data mutations (filesystem.c, fs_local.h):

• ds_provider struct extended with save and revert function pointers.
• FS_SaveDataSource(name): finds session → calls provider's save(root, params) → marks clean on success.
• FS_RevertDataSource(name): calls provider's revert(root, params) → marks clean.
• FS_MarkDataSourceDirty(name): sets session dirty flag for tracked changes.
• XML provider's _xml_ds_save: serializes DataObject tree to XML via FS_SerializeObjectToXmlString and writes to the file path from params.
• XML provider's _xml_ds_revert: invalidates session cache (next ResolveDataSource reloads).
• Screen.SaveChanges message registered as a hook point for UI-level save triggers.

Deprecation + sample migration (fs_xml.c, property_lua.c):

• DataContextSource handler: after provider lookup fails, emits Con_Warning before file-path fallback.
• property_lua.c kDataTypeObject handler: tries FS_ResolveDataSource before FS_LoadObject, with deprecation warning on fallback.
• All Example and Adventure XML files updated: ItemsSource="ApplicationData:Metrics" instead of Example/Data/ApplicationData:Metrics.

Optional schema (filesystem.c, filesystem.cgen):

• DataSource struct gains a Schema (string) field.
• ds_schema / ds_entity / ds_column structs hold parsed column metadata.
• _ParseSchema uses libxml2 to read <Schema> → <Entity> → <Column> hierarchy.
• Schema is parsed once on first resolve and cached in the session.
• FS_GetDataSourceSchema and FS_FindSchemaColumn provide runtime metadata access.
• Freed on session/registry cleanup.

Test strategy

Test file	Tests
test_layout.lua	DataSource declarations, provider resolution, name:child syntax, lifecycle cleanup, repeated load/unload, schema loading
test_pagehost_listbox.lua	SelectedItem default, programmatic, SelectItem message, click, custom ValueProperty, auto-select, reference stability, path resolution, GridBox inheritance

Files changed

File	Change
source/filesystem/filesystem.cgen	DataSource sealed struct (+ Schema field), Project.DataSources array
source/filesystem/filesystem.c	Provider registry, sessions, lifecycle, save/revert, schema parsing, XML save/revert
source/filesystem/fs_local.h	All internal API declarations
source/filesystem/fs_xml.c	Deprecation warning, name-based DataContextSource resolution
source/filesystem/w_filesystem.c	Provider registration with save/revert, unloadProject Lua API, Project.Release handler
source/core/property/property_lua.c	Provider lookup before file path for object properties
source/core/object/object_hierarchy.c	OBJ_FindPropertyByPath navigates through object properties
plugins/UIKit/UIKit.cgen	ItemsControl.SelectedItem, Screen.SaveChanges message
plugins/UIKit/ListBox.c	Set SelectedItem on selection change
plugins/UIKit/Screen.c	SaveChanges handler
samples/Example/package.lua	DataSources with Schema reference
samples/Example/Screens/Application.xml	Name-based ItemsSource/DataContextSource
samples/Example/Data/ApplicationData.Schema.xml	Sample schema
samples/Adventure/Screens/Adventures.xml	Name-based ItemsSource
samples/Adventure/Pages/GameList.xml	Name-based ItemsSource
tests/test_layout.lua	Lifecycle, schema, and provider tests
tests/test_pagehost_listbox.lua	SelectedItem tests

Validation

• make test-headless — all tests pass, zero regressions

[Copilot]

Pull request overview

This PR introduces package-level datasource declarations so package.lua can declare datasource provider metadata (name/type/params) and have it surface on Project.DataSources, alongside updates to sample packages and a regression test. It also updates Lua↔C property hydration to better handle struct/object tables used by package metadata.

Changes:

• Add Project.DataSources as a new schema surface (with a sealed DataSource struct) in the filesystem module.
• Declare XML datasources in samples/Example/package.lua and samples/Adventure/package.lua.
• Extend Lua property hydration/serialization to handle struct/object tables and array properties; add a focused layout test for package datasource declarations.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_layout.lua	Adds a regression test asserting package-level datasource declarations are present for the Example sample.
source/filesystem/filesystem.cgen	Adds the DataSource struct and the Project.DataSources array property to the filesystem schema.
source/core/property/property_lua.c	Updates Lua property read/write logic to better handle struct/object tables and array properties.
samples/Example/package.lua	Adds an Example datasource declaration (ApplicationData).
samples/Adventure/package.lua	Adds Adventure datasource declarations (Games, Tabs).

Comments suppressed due to low confidence (1)

source/core/property/property_lua.c:105

• Array property deserialization iterates the Lua table with lua_next but writes elements sequentially via an incrementing index. If the table is sparse (e.g. { [3] = ... }) or contains numeric keys outside 1..lua_rawlen, this will write past the calloc() buffer (or into a 0-length allocation), causing memory corruption/crashes. Use the numeric key to compute the destination index and validate it is within 1..numitems before writing.

    while (lua_next(L, idx) != 0) {
      if (lua_type(L, -2) != LUA_TNUMBER) {
        free(tmp);
        luaL_error(L, "Expected numeric keys in array table for property %s", prop->Name);
      }

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

source/core/property/property_lua.c:105

• Array-property decoding allocates storage based on lua_rawlen() but iterates elements via lua_next() without enforcing contiguous 1-based keys. Sparse arrays (e.g. { [1]=..., [3]=... }) will overflow the allocated buffer as i increments past numitems. Add a key check to require contiguous 1..N numeric indices (or switch to a lua_rawgeti loop).

    while (lua_next(L, idx) != 0) {
      if (lua_type(L, -2) != LUA_TNUMBER) {
        free(tmp);
        luaL_error(L, "Expected numeric keys in array table for property %s", prop->Name);
      }

[corepunch]

@copilot Fix webgl build, why is it broken?

[Copilot]

@copilot Fix webgl build, why is it broken?

Fixed in f007338. The WebGL job was failing because plugins/UIKit/ListBox.c calls PROP_NotifyChanged without including its declaration; the Emscripten/clang build treats that as an error, while the native build didn’t surface it.

[corepunch]

@copilot See if still makes sense to address the review comments, if it is, provide fixes

[Copilot]

@copilot See if still makes sense to address the review comments, if it is, provide fixes

Still-valid review comments were worth fixing, and I addressed them in 880fd39: guarded NULL-backed array serialization, fixed the DataContextSource="path:child" fallback to load the stripped path, and de-duplicated datasource registration with safe string termination. I also added a layout regression for the direct-path child fallback.

[corepunch]

@copilot Webgl fails, see what's wrong and fix

[Copilot]

@copilot Webgl fails, see what's wrong and fix

Fixed in bd2d37c. The WebGL job was failing because Con_Printf expands with a trailing semicolon under __EMSCRIPTEN__, so the comma-return form in source/filesystem/w_filesystem.c produced invalid syntax; I replaced that pattern there and in the same plugins/UIKit/ListBox.c handler with explicit Con_Printf(...) + return FALSE; blocks.